API reference · 6 endpoints

Compilation

Promotion triggers and sweeps that compile memories into higher-level knowledge.

GETList promotion decisions/v1/default/namespaces/{namespace_id}/compilation/promotions
POSTRun a compilation sweep/v1/default/namespaces/{namespace_id}/compilation/sweep
GETList compilation triggers/v1/default/namespaces/{namespace_id}/compilation/triggers
POSTCreate a compilation trigger/v1/default/namespaces/{namespace_id}/compilation/triggers
PATCHUpdate a compilation trigger/v1/default/namespaces/{namespace_id}/compilation/triggers/{trigger_id}
DELETEDelete a compilation trigger/v1/default/namespaces/{namespace_id}/compilation/triggers/{trigger_id}

GET/v1/default/namespaces/{namespace_id}/compilation/promotions

List promotion decisions

The decision log: what was promoted into this namespace, from where, by which trigger, and why.

Parameters

namespace_idstringpathrequired

outcome"promoted" | "rejected"query

trigger_idstring (uuid) | nullquery

source_namespace_idstring | nullquery

limitintegerquery

offsetintegerquery

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

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

Response · 200

{
  "items": [
    {
      "id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "namespace_id": "demo",
      "source_namespace_id": "nam_123",
      "source_memory_id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "trigger_id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "trigger_name": "trigger name",
      "outcome": "promoted",
      "decided_by": "tags",
      "created_at": "2025-08-12T10:00:00Z"
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}

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

POST/v1/default/namespaces/{namespace_id}/compilation/sweep

Run a compilation sweep

Evaluate every active trigger now. Incremental by default; backfill ignores the watermark.

Parameters

namespace_idstringpathrequired

Request body · application/json

backfillbooleandefault false

Ignore the watermark and evaluate the full history of each source.

curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/compilation/sweep" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "backfill": false
}'

import httpx

response = httpx.post(
    "https://api.illumina.sh/v1/default/namespaces/demo/compilation/sweep",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "backfill": False
    },
)
print(response.json())

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/compilation/sweep", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "backfill": false
  }),
});
console.log(await response.json());

Response · 200

{
  "evaluated": 1,
  "promoted": 1,
  "rejected": 1,
  "llm_calls": 1,
  "skipped_locked": false,
  "capped": false
}

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

GET/v1/default/namespaces/{namespace_id}/compilation/triggers

List compilation triggers

List the escalation triggers governing what this compilation namespace promotes.

Parameters

namespace_idstringpathrequired

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

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

Response · 200

{
  "items": [
    {
      "id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "workspace_id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "namespace_id": "demo",
      "name": "Demo namespace",
      "source_namespace_ids": [
        "source namespace ids"
      ],
      "tags": [
        "payments"
      ],
      "tags_match": "tags match",
      "fact_types": [
        "fact types"
      ],
      "judge": false,
      "is_active": false,
      "created_at": "2025-08-12T10:00:00Z",
      "updated_at": "2025-08-12T10:00:00Z"
    }
  ],
  "total": 1
}

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

POST/v1/default/namespaces/{namespace_id}/compilation/triggers

Create a compilation trigger

Add an escalation trigger. Tag, structured and similarity tiers cost nothing; the judge tier calls the model.

Parameters

namespace_idstringpathrequired

Request body · application/json

namestringrequired

source_namespace_idsstring[]default []

Standard namespaces to promote from; empty means every standard namespace.

tagsstring[]default []

tags_match"any" | "all" | "any_strict" | "all_strict"default "any"

tag_groupsobject | null

fact_typesstring[]default []

instructionstring | null

similarity_thresholdnumber | null

judgebooleandefault false

Escalate surviving candidates to an LLM judge. The only tier that spends.

is_activebooleandefault true

curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/compilation/triggers" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Demo namespace"
}'

import httpx

response = httpx.post(
    "https://api.illumina.sh/v1/default/namespaces/demo/compilation/triggers",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "name": "Demo namespace"
    },
)
print(response.json())

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/compilation/triggers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Demo namespace"
  }),
});
console.log(await response.json());

Response · 201

{
  "id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
  "workspace_id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
  "namespace_id": "demo",
  "name": "Demo namespace",
  "source_namespace_ids": [
    "source namespace ids"
  ],
  "tags": [
    "payments"
  ],
  "tags_match": "tags match",
  "fact_types": [
    "fact types"
  ],
  "judge": false,
  "is_active": false,
  "created_at": "2025-08-12T10:00:00Z",
  "updated_at": "2025-08-12T10:00:00Z"
}

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

PATCH/v1/default/namespaces/{namespace_id}/compilation/triggers/{trigger_id}

Update a compilation trigger

Partially update a trigger. The instruction is re-embedded only when its text changes.

Parameters

namespace_idstringpathrequired

trigger_idstring (uuid)pathrequired

Request body · application/json

namestring

source_namespace_idsstring[]default []

Standard namespaces to promote from; empty means every standard namespace.

tagsstring[]default []

tags_match"any" | "all" | "any_strict" | "all_strict"default "any"

tag_groupsobject | null

fact_typesstring[]default []

instructionstring | null

similarity_thresholdnumber | null

judgebooleandefault false

Escalate surviving candidates to an LLM judge. The only tier that spends.

is_activebooleandefault true

curl -X PATCH "https://api.illumina.sh/v1/default/namespaces/demo/compilation/triggers/tri_123" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Demo namespace",
  "source_namespace_ids": [],
  "tags": [],
  "tags_match": "any"
}'

import httpx

response = httpx.patch(
    "https://api.illumina.sh/v1/default/namespaces/demo/compilation/triggers/tri_123",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "name": "Demo namespace",
        "source_namespace_ids": [],
        "tags": [],
        "tags_match": "any"
    },
)
print(response.json())

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/compilation/triggers/tri_123", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Demo namespace",
    "source_namespace_ids": [],
    "tags": [],
    "tags_match": "any"
  }),
});
console.log(await response.json());

Response · 200

{
  "id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
  "workspace_id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
  "namespace_id": "demo",
  "name": "Demo namespace",
  "source_namespace_ids": [
    "source namespace ids"
  ],
  "tags": [
    "payments"
  ],
  "tags_match": "tags match",
  "fact_types": [
    "fact types"
  ],
  "judge": false,
  "is_active": false,
  "created_at": "2025-08-12T10:00:00Z",
  "updated_at": "2025-08-12T10:00:00Z"
}

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

DELETE/v1/default/namespaces/{namespace_id}/compilation/triggers/{trigger_id}

Delete a compilation trigger

Remove a trigger. Already-promoted memories and their decision-log rows are kept.

Parameters

namespace_idstringpathrequired

trigger_idstring (uuid)pathrequired

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

import httpx

response = httpx.delete(
    "https://api.illumina.sh/v1/default/namespaces/demo/compilation/triggers/tri_123",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
print(response.json())

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

Response · 200

{
  "deleted": false
}

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

Getting started

Core concepts

SDKs & tools

API reference

Resources

Compilation

List promotion decisions

Parameters

Run a compilation sweep

Parameters

Request body · application/json

List compilation triggers

Parameters

Create a compilation trigger

Parameters

Request body · application/json

Update a compilation trigger

Parameters

Request body · application/json

Delete a compilation trigger

Parameters

Getting started

Core concepts

SDKs & tools

API reference

Resources

List promotion decisions

Parameters

Run a compilation sweep

Parameters

Request body · application/json

List compilation triggers

Parameters

Create a compilation trigger

Parameters

Request body · application/json

Update a compilation trigger

Parameters

Request body · application/json

Delete a compilation trigger

Parameters

Search docs