API reference · 10 endpoints

Automations

Standing reflect queries that keep themselves up to date as new memories land.

GETList automation templates/v1/default/automations/templates
GETList automations/v1/default/namespaces/{namespace_id}/automations
POSTCreate automation/v1/default/namespaces/{namespace_id}/automations
GETGet automation/v1/default/namespaces/{namespace_id}/automations/{automation_id}
PATCHUpdate automation/v1/default/namespaces/{namespace_id}/automations/{automation_id}
DELETEDelete automation/v1/default/namespaces/{namespace_id}/automations/{automation_id}
POSTClear automation content/v1/default/namespaces/{namespace_id}/automations/{automation_id}/clear
GETGet automation history/v1/default/namespaces/{namespace_id}/automations/{automation_id}/history
POSTRefresh automation/v1/default/namespaces/{namespace_id}/automations/{automation_id}/refresh
GETGet automation run history/v1/default/namespaces/{namespace_id}/automations/{automation_id}/runs

GET/v1/default/automations/templates

List automation templates

The static catalog of starter automation templates (name, source query, and a suggested schedule) used to pre-fill the create form.

curl -X GET "https://api.illumina.sh/v1/default/automations/templates" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"

const response = await fetch("https://api.illumina.sh/v1/default/automations/templates", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}` },
});
console.log(await response.json());

Response · 200

{}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410see error reference

GET/v1/default/namespaces/{namespace_id}/automations

List automations

List user-curated living documents that stay current.

Parameters

namespace_idstringpathrequired

tagsstring[]query

Filter by tags

tags_match"any" | "all" | "exact"query

How to match tags

detail"metadata" | "content" | "full"query

Detail level: 'metadata' (names/tags only), 'content' (adds content/config), 'full' (includes reflect_response)

limitintegerquery

offsetintegerquery

curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/automations" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/automations", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}` },
});
console.log(await response.json());

Response · 200

{
  "items": [
    {
      "id": "ite_123",
      "namespace_id": "demo",
      "name": "Demo namespace"
    }
  ]
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

POST/v1/default/namespaces/{namespace_id}/automations

Create an automation by running reflect with the source query in the background. Returns an operation ID to track progress. The content is auto-generated by the reflect endpoint. Use the operations endpoint to check completion status.

Parameters

namespace_idstringpathrequired

Request body · application/json

idstring | null

Optional custom ID for the automation (alphanumeric lowercase with hyphens)

namestringrequired

Human-readable name for the automation

source_querystringrequired

The query to run to generate content

tagsstring[]default []

Tags for scoped visibility

max_tokensintegerdefault 2048

Maximum tokens for generated content

triggerunknown | nulldefault {}

Trigger settings

curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/automations" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "team-communication",
  "max_tokens": 2048,
  "name": "Team Communication Preferences",
  "source_query": "How does the team prefer to communicate?",
  "tags": [
    "team"
  ],
  "trigger": {
    "refresh_after_consolidation": false
  }
}'

import httpx

response = httpx.post(
    "https://api.illumina.sh/v1/default/namespaces/demo/automations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "id": "team-communication",
        "max_tokens": 2048,
        "name": "Team Communication Preferences",
        "source_query": "How does the team prefer to communicate?",
        "tags": [
            "team"
        ],
        "trigger": {
            "refresh_after_consolidation": False
        }
    },
)
print(response.json())

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/automations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "id": "team-communication",
    "max_tokens": 2048,
    "name": "Team Communication Preferences",
    "source_query": "How does the team prefer to communicate?",
    "tags": [
      "team"
    ],
    "trigger": {
      "refresh_after_consolidation": false
    }
  }),
});
console.log(await response.json());

Response · 200

{
  "operation_id": "ope_123"
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

GET/v1/default/namespaces/{namespace_id}/automations/{automation_id}

Get automation

Get a specific automation by ID.

Parameters

namespace_idstringpathrequired

automation_idstringpathrequired

detail"metadata" | "content" | "full"query

Detail level: 'metadata' (names/tags only), 'content' (adds content/config), 'full' (includes reflect_response)

curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/automations/aut_123" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/automations/aut_123", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}` },
});
console.log(await response.json());

Response · 200

{
  "id": "ite_123",
  "namespace_id": "demo",
  "name": "Demo namespace"
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

PATCH/v1/default/namespaces/{namespace_id}/automations/{automation_id}

Update automation

Update an automation's name and/or source query.

Parameters

namespace_idstringpathrequired

automation_idstringpathrequired

Request body · application/json

namestring | null

New name for the automation

source_querystring | null

New source query for the automation

max_tokensinteger | null

Maximum tokens for generated content

tagsstring[]

Tags for scoped visibility

triggerunknown | null

Trigger settings

curl -X PATCH "https://api.illumina.sh/v1/default/namespaces/demo/automations/aut_123" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "max_tokens": 4096,
  "name": "Updated Team Communication Preferences",
  "source_query": "How does the team prefer to communicate?",
  "tags": [
    "team",
    "communication"
  ],
  "trigger": {
    "refresh_after_consolidation": true
  }
}'

import httpx

response = httpx.patch(
    "https://api.illumina.sh/v1/default/namespaces/demo/automations/aut_123",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "max_tokens": 4096,
        "name": "Updated Team Communication Preferences",
        "source_query": "How does the team prefer to communicate?",
        "tags": [
            "team",
            "communication"
        ],
        "trigger": {
            "refresh_after_consolidation": True
        }
    },
)
print(response.json())

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/automations/aut_123", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "max_tokens": 4096,
    "name": "Updated Team Communication Preferences",
    "source_query": "How does the team prefer to communicate?",
    "tags": [
      "team",
      "communication"
    ],
    "trigger": {
      "refresh_after_consolidation": true
    }
  }),
});
console.log(await response.json());

Response · 200

{
  "id": "ite_123",
  "namespace_id": "demo",
  "name": "Demo namespace"
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

DELETE/v1/default/namespaces/{namespace_id}/automations/{automation_id}

Delete automation

Delete an automation.

Parameters

namespace_idstringpathrequired

automation_idstringpathrequired

curl -X DELETE "https://api.illumina.sh/v1/default/namespaces/demo/automations/aut_123" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/automations/aut_123", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}` },
});
console.log(await response.json());

Response · 200

null

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

POST/v1/default/namespaces/{namespace_id}/automations/{automation_id}/clear

Clear automation content

Clear an automation's content so the next refresh performs a full re-synthesis. This is useful for delta-mode models that have accumulated drift over many incremental refreshes. After clearing, call the /refresh endpoint to trigger a clean full rebuild.

Parameters

namespace_idstringpathrequired

automation_idstringpathrequired

curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/automations/aut_123/clear" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/automations/aut_123/clear", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}` },
});
console.log(await response.json());

Response · 200

{
  "id": "ite_123",
  "namespace_id": "demo",
  "name": "Demo namespace"
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

GET/v1/default/namespaces/{namespace_id}/automations/{automation_id}/history

Get automation history

Get the refresh history of an automation, showing content changes over time.

Parameters

namespace_idstringpathrequired

automation_idstringpathrequired

curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/automations/aut_123/history" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/automations/aut_123/history", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}` },
});
console.log(await response.json());

Response · 200

null

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

POST/v1/default/namespaces/{namespace_id}/automations/{automation_id}/refresh

Refresh automation

Submit an async task to re-run the source query through reflect and update the content.

Parameters

namespace_idstringpathrequired

automation_idstringpathrequired

curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/automations/aut_123/refresh" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/automations/aut_123/refresh", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}` },
});
console.log(await response.json());

Response · 200

{
  "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

GET/v1/default/namespaces/{namespace_id}/automations/{automation_id}/runs

Get automation run history

List the newest-first refresh runs of an automation, each with its trigger cause (manual/schedule/consolidation) and outcome (changed, or no_new_facts for a quiet-day skip). Terminally failed refreshes are not included; they appear in the failed-operations DLQ.

Parameters

namespace_idstringpathrequired

automation_idstringpathrequired

curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/automations/aut_123/runs" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/automations/aut_123/runs", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}` },
});
console.log(await response.json());

Response · 200

null

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

Getting started

Core concepts

SDKs & tools

API reference

Resources

Automations

List automation templates

List automations

Parameters

Create automation

Parameters

Request body · application/json

Get automation

Parameters

Update automation

Parameters

Request body · application/json

Delete automation

Parameters

Clear automation content

Parameters

Get automation history

Parameters

Refresh automation

Parameters

Get automation run history

Parameters

Getting started

Core concepts

SDKs & tools

API reference

Resources

Parameters

Parameters

Request body · application/json

Parameters

Parameters

Request body · application/json

Parameters

Parameters

Parameters

Parameters

Parameters

Search docs