Illumina Docs — Documentation for Illumina — the memory engine for AI agents. Retain, recall, and reflect over organizational knowledge.

API base URL: https://api.illumina.sh

===/docs/overview===

# Get started with Illumina

A hosted memory engine for AI agents. Retain raw text, recall scored context, reflect across everything a namespace knows.

- [Create a workspace](https://illumina.sh)
- [Quickstart](/docs/quickstart)

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/memories" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"content":"Ada shipped the payments rewrite in Q3 2025."}]}'

curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/memories/recall" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"who shipped payments?","budget":"mid"}'
```

```python
from illumina_client import Illumina

client = Illumina(
    base_url="https://api.illumina.sh",
    api_key="sub_live_...",
)

client.retain(
    namespace_id="demo",
    content="Ada shipped the payments rewrite in Q3 2025.",
)

results = client.recall(
    namespace_id="demo",
    query="who shipped payments?",
    budget="mid",
)
```

```typescript
import { IlluminaClient } from "@illumina/client";

const client = new IlluminaClient({
  baseUrl: "https://api.illumina.sh",
  apiKey: "sub_live_...",
});

await client.retain("demo", "Ada shipped the payments rewrite in Q3 2025.");

const results = await client.recall("demo", "who shipped payments?", {
  budget: "mid",
});
```

## Three core operations

Everything in Illumina builds on three operations.

- [Retain](/docs/concepts/retain) — Turns raw text or an uploaded file into structured memory — facts, entities, and the relationships between them. Asynchronous: returns an `operation_id` you can poll.
- [Recall](/docs/concepts/recall) — Answers a query by fusing semantic, lexical, graph, and temporal retrieval, then reranking by relevance, recency, and corroboration.
- [Reflect](/docs/concepts/reflect) — Runs an agentic loop over a namespace to answer higher-level questions and surface patterns across many memories.

A background consolidation pass groups corroborating facts into observations
over time, so a namespace gets more useful the longer it lives.

## Memory model

Every memory unit has one of four [fact types](/docs/concepts/fact-types):

| Type | What it holds |
| --- | --- |
| `world` | Objective, external facts. The default classification. |
| `experience` | First-person actions and observations by the memory's owner. |
| `decision` | Durable commitments with a supersession lifecycle. |
| `observation` | Synthesized by consolidation; never written directly. |

Memories link to extracted **entities** and to each other, forming a knowledge
graph you can traverse through the [graph and entity endpoints](/api-reference/entities).
Related memories cluster into [communities](/api-reference/communities), and an
[ontology](/api-reference/ontology) describes the entity and relationship types
in play.

## Jump straight in

- [REST API](/api-reference) — Every endpoint with parameters, response shapes, and copy-ready samples.
- [MCP server](/mcp/overview) — Give Claude Code, Cursor, or any MCP client direct memory tools.
- [Python SDK](/sdks/python) — `illumina-client` — sync and async clients over the full surface.
- [TypeScript SDK](/sdks/typescript) — `@illumina/client` — typed and promise-based.
- [Authentication](/docs/authentication) — Workspace keys, namespace scoping, and rotation.
- [Errors and rate limits](/docs/errors) — The shared error envelope, status vocabulary, and per-plan limits.

===/docs/quickstart===

# Quickstart

Retain your first memory and recall it in five minutes.

## 1. Get an API key

Create a workspace at [illumina.sh](https://illumina.sh) and mint an API key
from the dashboard. Keys start with `sub_live_` and are shown once at creation.

```bash
export ILLUMINA_API_KEY=sub_live_...
```

All requests authenticate with a bearer header. See
[Authentication](/docs/authentication) for scoping and key management.

## 2. Create a namespace

Memories live in namespaces. Retain does not auto-create one, so create it
first:

```bash
curl -X PUT "https://api.illumina.sh/v1/default/namespaces/demo" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## 3. Retain a memory

Write raw text into the namespace. Illumina extracts facts, entities, and
relationships asynchronously:

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/memories" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"content":"Ada shipped the payments rewrite in Q3 2025."}]}'
```

> Retain returns an `operation_id` immediately and extracts facts in the
> background. Poll [the operation](/api-reference/operations) if you need to know
> when it lands, or wait a few seconds before your first recall.

## 4. Recall

Query the namespace. `budget` controls retrieval effort (`low`, `mid`, or
`high`):

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/memories/recall" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"who shipped payments?","budget":"mid","max_tokens":2048}'
```

## 5. Reflect

Ask a higher-level question over everything the namespace knows:

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/reflect" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"summarize Ada'\''s recent work","budget":"low","max_tokens":512}'
```

## The same flow in an SDK

```python title="Python"
from illumina_client import Illumina

client = Illumina(base_url="https://api.illumina.sh", api_key="sub_live_...")
client.create_namespace(namespace_id="demo")
client.retain(namespace_id="demo", content="Ada shipped the payments rewrite in Q3.")
results = client.recall(namespace_id="demo", query="who shipped payments?")
answer = client.reflect(namespace_id="demo", query="summarize Ada's recent work")
```

```typescript title="TypeScript"
import { IlluminaClient } from "@illumina/client";

const client = new IlluminaClient({ baseUrl: "https://api.illumina.sh", apiKey: "sub_live_..." });
await client.createNamespace("demo");
await client.retain("demo", "Ada shipped the payments rewrite in Q3.");
const results = await client.recall("demo", "who shipped payments?");
const answer = await client.reflect("demo", "summarize Ada's recent work");
```

## Next steps

- [Fact types](/docs/concepts/fact-types) — Control how memories are classified.
- [Recall](/docs/concepts/recall) — Budgets, scoring, and filtering.
- [API reference](/api-reference) — Every endpoint, with copy-ready examples.

===/docs/authentication===

# Authentication

API keys, bearer auth, and namespace scoping.

Every request to `https://api.illumina.sh` authenticates with a bearer token:

```bash
curl "https://api.illumina.sh/v1/default/namespaces" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

## API keys

Workspace API keys start with `sub_live_` and are minted from the dashboard at
[illumina.sh](https://illumina.sh). The full key is shown once at creation —
store it in a secret manager. Keys are hashed at rest and can be revoked at any
time from the dashboard.

Free workspaces can hold up to 5 API keys; pro workspaces raise the cap.

## Namespace scoping

A key can be scoped to a subset of the workspace's namespaces. Scoping is
enforced on every transport — REST and [MCP](/mcp/overview) alike:

- A request against a namespace outside the key's scope answers `404`, not
  `403`. Existence never leaks across scopes.
- Namespace listings are filtered to the key's scope.
- A scoped key cannot create namespaces. Use an unscoped key (or the
  dashboard) to bootstrap namespaces, then hand agents a scoped key.

## The URL shape

Paths look like `/v1/default/namespaces/{namespace_id}/...`. The `default`
segment is a fixed literal — your workspace identity comes entirely from the
API key, not the URL. Namespace ids are yours to choose (`demo`,
`support-agent`, `team-payments`).

## Request hygiene

- Send the key only in the `Authorization` header — never in query strings.
- Rotate keys by minting a replacement, migrating traffic, then revoking the
  old key.
- Scope one key per agent or integration so a leak has a small blast radius.

===/docs/rate-limits===

# Rate limits

Per-workspace request rates, in-flight caps, and monthly quotas.

Limits apply per workspace, across all billable operations.

## Request rate

| Plan | Requests per minute | In-flight retain/reflect |
| --- | --- | --- |
| Free | 60 | 2 |
| Pro | 600 | 10 |

The per-minute limit is a token bucket, so short bursts above the sustained
rate are absorbed. The in-flight cap bounds concurrent heavy operations
(retain and reflect) separately.

Exceeding either answers `429` with a `Retry-After` header:

```json
{
  "detail": "rate limited",
  "code": "rate_limited"
}
```

Honor `Retry-After` and retry with backoff. SDK clients surface the header on
the raised error.

## Monthly quotas

| Quota | Free | Pro |
| --- | --- | --- |
| Retain operations | 1,000 | 50,000 |
| Recall operations | 5,000 | 50,000 |
| Reflect operations | 50 | 50,000 |
| Namespaces | 3 | Higher caps |
| Blob storage | 1 GiB | 50 GiB |

A request past an exhausted quota answers `402` before the request body is
even parsed. Every LLM-consuming path is metered, not just retain: file
uploads, document reprocessing, and connector ingestion meter as retain;
manual consolidation and automation refresh meter as reflect.

Usage is visible in the dashboard, and upgrading lifts the caps immediately.

## Service backstops

Independent of plan limits, the service sheds excess load with `503` +
`Retry-After` rather than queuing, and any single request is bounded to 300
seconds. Treat `503` as retryable with backoff.

===/docs/errors===

# Errors

Error envelope, status codes, and retry guidance.

Errors return JSON with a `detail` message; some carry an additional machine
`code`:

```json
{
  "detail": "rate limited",
  "code": "rate_limited"
}
```

Validation failures (`422`) use a structured `detail` array instead, with the
offending location and message per field:

```json
{
  "detail": [
    {
      "loc": ["body", "items"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

## Status codes

| Status | Meaning | Retry? |
| --- | --- | --- |
| `400` | Malformed request. | No — fix the request. |
| `401` | Missing or invalid API key. | No — check the key. |
| `402` | Monthly quota exhausted. | No — upgrade or wait for the cycle reset. |
| `403` | Authenticated but not permitted. | No. |
| `404` | Not found — including namespaces outside your key's scope. | No. |
| `405` | Wrong HTTP method for the path. | No. |
| `409` | Conflict — e.g. retrying an operation that is not dead-lettered. | No — check state first. |
| `410` | Resource gone. | No. |
| `413` | Upload too large. | No — reduce the file size. |
| `422` | Body failed validation. | No — fix the fields in `detail`. |
| `429` | Rate limited. | Yes — honor `Retry-After`. |
| `503` | Overloaded; request shed. | Yes — retry with backoff. |

## Retry guidance

Only `429` and `503` are retryable, and both include a `Retry-After` header.
Use exponential backoff with jitter and cap total attempts. Retain is
idempotent per content batch — a duplicate in-flight retain collapses onto
the existing operation — so retrying a timed-out retain is safe.

## Asynchronous failures

Retain processes asynchronously. A `200` from retain means the work was
accepted; extraction failures surface on the
[operations API](/api-reference/operations). A retain that exhausts its
retries dead-letters: list failed work with `state=failed`, read the terminal
error on the status route, and re-run it with the
[retry endpoint](/api-reference/operations#retry_operation).

===/docs/concepts/retain===

# Retain

How raw text and files become structured memory.

[`POST /memories`](/api-reference/memory#retain_memories) writes memory into a
namespace. You send raw content; Illumina extracts the structure.

## What happens on retain

1. **Fact extraction** — the content is decomposed into discrete semantic
   facts using an LLM with forced tool-use.
2. **Entity recognition** — people, systems, and concepts are extracted and
   linked to existing entities in the namespace.
3. **Embedding** — each fact is embedded for semantic retrieval.
4. **Deduplication** — near-duplicate facts merge instead of accumulating.
5. **Linking** — temporal, semantic, and entity links connect the new facts
   into the namespace's knowledge graph.

Retain is asynchronous: the response carries an `operation_id` you can track
on the [operations API](/api-reference/operations). A duplicate retain of the
same content collapses onto the in-flight operation, so retries are safe.

## Shaping what gets retained

Each item accepts more than `content`:

- `timestamp` — when the fact happened (defaults to now). Drives temporal
  recall and recency scoring.
- `context` — a short hint about the setting ("standup", "support ticket").
- `document_id` — groups items into a [document](/api-reference/documents).
  Retaining the same `document_id` again upserts: old facts from that
  document are replaced (or appended, with `update_mode: "append"`).
- `tags` — labels for filtering recall and reflect later.
- `metadata` — arbitrary string key-values carried on the memory.
- `fact_type` — force `world`, `experience`, or `decision` instead of LLM
  classification. See [Fact types](/docs/concepts/fact-types).
- `entities` — pre-extracted entities to link explicitly.

## Files

[`POST /files/retain`](/api-reference/files#file_retain) accepts uploads
(PDF, DOCX, PPTX, XLSX, HTML, images). Documents are parsed — with OCR for
scanned pages and images — chunked, and retained through the same extraction
pipeline. Namespace [directives](/api-reference/directives) and retain
configuration apply to file content the same way they apply to text.

## Steering extraction

Per-namespace [configuration](/api-reference/namespaces#get_namespace_config)
sets a retain mission, extraction mode, custom instructions, and chunk size.
[Directives](/docs/concepts/namespaces) add standing instructions that bias
what extraction keeps and how it phrases facts.

===/docs/concepts/recall===

# Recall

Multi-strategy retrieval, fused and scored.

[`POST /memories/recall`](/api-reference/memory#recall_memories) answers a
query with the most relevant memories in the namespace.

## How recall retrieves

Four retrieval arms run in parallel and their candidates are fused:

- **Semantic** — embedding similarity against the query.
- **Lexical** — full-text search for exact terms the embedding may miss.
- **Graph** — link expansion from strong hits to connected facts.
- **Temporal** — time-anchored retrieval when the query implies a period.

Candidates are reranked, then scored by **relevance**, **recency**, and
**corroboration**. Standing decisions never decay below neutral recency, so
policy stays findable long after it was made.

## Budget

`budget` trades latency for depth:

| Budget | Behavior |
| --- | --- |
| `low` | Fewer candidates, single-pass. Fastest. |
| `mid` | The default balance. |
| `high` | Widest retrieval and reranking effort. |

`max_tokens` caps the size of the result set, so the response drops straight
into a prompt.

## Filtering and extras

- `types` — restrict fact types. The REST endpoint defaults to all four;
  pass `["world", "experience", "decision"]` to exclude synthesized
  observations.
- `tags` + `tags_match` — filter by retain-time tags (`any`, `all`, or the
  `_strict` variants that exclude untagged memories). `tag_groups` composes
  boolean tag expressions.
- `query_timestamp` — anchor "recent" to a different point in time.
- `include` options — entity observations, raw source chunks, and the source
  facts behind observations can be inlined in the response, each with its own
  token cap.
- `trace` — return scoring detail for debugging retrieval.

===/docs/concepts/reflect===

# Reflect

Agentic reasoning over everything a namespace knows.

[`POST /reflect`](/api-reference/memory#reflect) goes beyond retrieval: it
runs an agentic loop over the namespace's memories to answer higher-level
questions, synthesize summaries, and surface patterns no single memory
states.

Where [recall](/docs/concepts/recall) returns memories for *your* prompt,
reflect returns an *answer* — it recalls, reasons, recalls again if needed,
and writes a synthesis.

## Request shape

```json
{
  "query": "what has the payments team decided this quarter?",
  "budget": "mid",
  "max_tokens": 1024
}
```

- `budget` — `low` for quick syntheses, `high` for deep multi-step reasoning.
- `context` — extra framing for the answer ("you are briefing a new hire").
- `response_schema` — a JSON Schema; reflect returns structured output
  matching it instead of prose.
- `tags`, `tags_match`, `tag_groups`, `fact_types` — scope which memories the
  loop may draw on.
- `include_facts` — return the supporting facts alongside the answer.
- `exclude_automations` — leave standing automation outputs out of the
  evidence.

## Namespace identity

Reflect answers in light of the namespace's configured **reflect mission**
and disposition — set them via
[namespace config](/api-reference/namespaces#update_namespace_config). A
support namespace can answer cautiously and cite tickets; an engineering
namespace can be terse and technical.

## Automations

An [automation](/api-reference/automations) is a standing reflect query that
re-runs as new memories land, so dashboards and briefings stay current
without polling. Reflect powers each refresh; results are queryable per
automation.

Reflect meters against the reflect quota — see
[Rate limits](/docs/rate-limits).

===/docs/concepts/fact-types===

# Fact types

world, experience, decision, and observation — and when each applies.

Every memory unit carries one of four fact types. The type is assigned at
retain time — by LLM classification, or deterministically when you set
`fact_type` on the item.

## world

Objective, external facts about people, events, systems, and general
knowledge. The default classification.

> "Stripe caps webhook retries at 72 hours."

## experience

First-person actions and observations by the memory's owner — what the agent
did and saw.

> "I migrated the billing cron to the new scheduler."

## decision

Durable commitments that settle what will (or won't) be done: architecture
decisions, policy calls, go/no-go outcomes.

> "We will use Postgres for the queue; no separate broker."

Decisions carry a [lifecycle](/docs/concepts/decisions) — they stand until a
later decision supersedes them — and standing decisions never decay below
neutral recency in recall scoring, so established policy stays findable.

Set `fact_type: "decision"` on a retain item to record one deterministically
rather than relying on classification.

## observation

Synthesized by background [consolidation](/docs/concepts/consolidation) from
corroborating source facts. Observations are never written directly — they
are the system's own distillation of repeated evidence.

## Recall scope

The REST recall endpoint defaults to all four types. Pass `types` to narrow:

```json
{
  "query": "deployment policy",
  "types": ["world", "decision"]
}
```

The MCP tools and SDKs default to world + experience + decision, with
observations opt-in.

===/docs/concepts/decisions===

# Decision lifecycle

Standing, superseded, and reconciled — how commitments evolve.

Decisions are the fact type with state. A decision is **standing** from the
moment it is retained until a later decision supersedes it.

## Supersession

- **Standing** — A decision enters memory as standing. It ranks in recall as though it were said today, no matter how old it is.
- **Contradiction detected** — A later retain extracts a decision that contradicts or replaces it. Illumina links the pair with a supersedes edge.
- **Superseded** — The old decision is marked superseded and the change is written to its history. The structured rationale survives in metadata.decision.rationale.
- **Reconciled** — A reconcile sweep walks the namespace for contradictory standing decisions and links whatever automatic detection missed.

The structured rationale survives supersession, so you can always ask why a
commitment was made even after it has been replaced.

The result is a chain you can walk: the
[lineage endpoint](/api-reference/memory#get_memory_lineage) returns a
decision's ancestry, and its
[history](/api-reference/memory#get_observation_history) records every state
change.

## Manual control

Automatic detection can be overridden:

- [`POST /memories/{memory_id}/supersede`](/api-reference/memory#supersede_decision)
  marks a decision superseded explicitly.
- [`DELETE /memories/{memory_id}/supersede`](/api-reference/memory#revive_decision)
  revives it to standing.
- [`POST /decisions/reconcile`](/api-reference/memory#reconcile_decisions)
  sweeps the namespace for contradictory standing decisions and links what
  automatic detection missed.

## Why it matters for recall

Standing decisions never decay below neutral recency in
[recall scoring](/docs/concepts/recall). A policy set two years ago ranks
like it was said yesterday — until it is superseded, at which point the
replacement takes its place and the old one fades unless asked for
explicitly.

Record decisions deterministically by setting `fact_type: "decision"` on the
retain item; see [Fact types](/docs/concepts/fact-types).

===/docs/concepts/consolidation===

# Consolidation

Background synthesis that turns repeated evidence into observations.

Namespaces improve with age. A background consolidation pass periodically
groups corroborating facts and synthesizes **observations** — memory units
that state what the evidence repeatedly shows.

> Facts: "Ada fixed the payments retry bug", "Ada shipped the payments
> rewrite", "Ada reviewed the payments oncall runbook"
>
> Observation: "Ada is the payments domain expert."

## Properties

- Observations carry the `observation` [fact type](/docs/concepts/fact-types)
  and are never written directly — consolidation is their only source.
- Each observation links to its source facts. Recall can inline them with
  `include_source_facts`.
- Consolidation is incremental and idempotent; it does not duplicate
  observations for evidence it has already folded in.

## Control

- Enable or steer synthesis per namespace via
  [config](/api-reference/namespaces#update_namespace_config)
  (`enable_observations`, `observations_mission`).
- Trigger a pass on demand with
  [`POST /consolidate`](/api-reference/namespaces#trigger_consolidation)
  (meters as a reflect operation).
- Recover a stuck run with
  [`POST /consolidation/recover`](/api-reference/namespaces#recover_consolidation).
- Clear synthesized observations —
  [namespace-wide](/api-reference/namespaces#clear_observations) or
  [per memory](/api-reference/memory#clear_memory_observations) — and the
  next pass rebuilds from surviving evidence.

## Observations in recall

The REST recall endpoint includes observations by default (`types` narrows
this). They rank by the same relevance/recency/corroboration scoring as other
memories, and corroboration is where observations shine — they carry the
weight of every source fact behind them.

===/docs/concepts/namespaces===

# Namespaces

The unit of memory isolation, identity, and configuration.

A namespace is one memory space: an isolated set of memories, entities,
documents, and configuration. Give each agent, team, or domain its own
namespace and memories never bleed across the boundary.

## Lifecycle

Namespaces are created explicitly —
[`PUT /namespaces/{namespace_id}`](/api-reference/namespaces#create_or_update_namespace)
— retain does not auto-create them. Ids are yours to choose (`support-agent`,
`team-payments`). [Delete](/api-reference/namespaces#delete_namespace)
removes the namespace and everything in it.

Free workspaces hold 3 namespaces; pro raises the cap.

## Identity and configuration

[Namespace config](/api-reference/namespaces#get_namespace_config) shapes
behavior on both sides of the memory:

- **Retain side** — a retain mission, extraction mode, custom extraction
  instructions, and chunk size steer what gets kept.
- **Reflect side** — a reflect mission and disposition (skepticism,
  literalism, empathy) steer how [reflect](/docs/concepts/reflect) answers.
- **Observations** — enable and steer
  [consolidation](/docs/concepts/consolidation).

Config updates are partial ([`PATCH`](/api-reference/namespaces#update_namespace_config));
[`DELETE /config`](/api-reference/namespaces#reset_namespace_config) resets
to defaults.

## Standing instructions

[Directives](/api-reference/directives) are per-namespace standing
instructions that bias retain and recall continuously — "prefer customer
names over ticket numbers", "treat runbook facts as authoritative".

## Templates

[Export](/api-reference/namespace-templates#export_namespace_template) a
namespace's configuration as a template and
[import](/api-reference/namespace-templates#import_namespace_template) it to
stamp out consistent namespaces per customer or per environment.

## Observability

Per-namespace [stats](/api-reference/namespaces#get_agent_stats), a
[memories timeseries](/api-reference/namespaces#get_memories_timeseries), and
an [audit trail](/api-reference/audit) of recall and MCP activity.

===/sdks/python===

# Python SDK

Install and use illumina-client, the Python SDK for the Illumina API.

The Python SDK is published as `illumina-client` and imported as
`illumina_client`. Its `Illumina` class wraps every common operation, and every
method ships with an `a`-prefixed async twin (`retain`/`aretain`,
`recall`/`arecall`, and so on) that uses its own transport — neither variant
depends on the other's event loop.

## Install

```bash
pip install illumina-client
```

Requires Python 3.10 or newer.

## Initialize

Construct the client with the hosted base URL and your API key. The key is sent
as a bearer token on every request:

```python
from illumina_client import Illumina

client = Illumina(base_url="https://api.illumina.sh", api_key="sub_live_...")
```

The full constructor is `Illumina(base_url, api_key=None, timeout=300.0,
user_agent=None)`:

| Parameter | Description |
| --- | --- |
| `base_url` | Required. The API base URL — `https://api.illumina.sh` for the hosted service. |
| `api_key` | Your `sub_live_...` key, sent as `Authorization: Bearer <key>`. |
| `timeout` | Request timeout in seconds (default `300.0`). |
| `user_agent` | Overrides the default `illumina-client-python/<version>` header. |

### Async

Every method has an async counterpart prefixed with `a`. The client is also a
context manager (sync and async) that closes its transports on exit:

```python
import asyncio
from illumina_client import Illumina

async def main():
    async with Illumina(base_url="https://api.illumina.sh", api_key="sub_live_...") as client:
        await client.aretain(namespace_id="alice", content="Alice loves AI")
        response = await client.arecall(namespace_id="alice", query="What does Alice like?")
        for result in response.results:
            print(result.text)

asyncio.run(main())
```

## Core operations

Memories live in namespaces, and retain does not auto-create one — create it
first:

```python
client.create_namespace(namespace_id="alice")
```

### Retain

Store raw text; Illumina extracts facts, entities, and relationships:

```python
client.retain(
    namespace_id="alice",
    content="Ada shipped the payments rewrite in Q3 2025.",
    context="standup notes",
    tags=["work"],
)
```

`retain` also accepts `timestamp`, `document_id`, `metadata`, `entities`
(`[{"text": "...", "type": "..."}]`), `update_mode` (`"replace"` or
`"append"`), `fact_type` (`"world"`, `"experience"`, or `"decision"`), and
`retain_async=True` to process in the background.

Use `retain_batch` for multiple memories in one request — each item is a dict
with a required `content` key:

```python
client.retain_batch(
    namespace_id="alice",
    items=[
        {"content": "Alice loves hiking"},
        {"content": "Alice visited Paris", "context": "travel", "timestamp": "2024-07-01"},
    ],
)
```

`retain_files(namespace_id, files, context=None, files_metadata=None)` uploads
files, always processes them asynchronously, and returns operation IDs for
tracking progress.

### Recall

Query a namespace by semantic similarity. `budget` (`"low"`, `"mid"`,
`"high"`) controls retrieval effort and defaults to `"mid"`; `max_tokens`
defaults to `4096`:

```python
response = client.recall(
    namespace_id="alice",
    query="What are Alice's hobbies?",
    budget="mid",
    include_entities=True,
)
for result in response.results:
    print(result.text, result.type_)
```

Other keyword arguments: `types` (filter by fact type), `tags` and `tags_match`
(`"any"`, `"all"`, `"any_strict"`, `"all_strict"`), `tag_groups` (compound
boolean tag filters), `include_chunks`, `include_source_facts`,
`query_timestamp`, and `trace`.

`RecallResponse` is iterable, supports `len()`, and has `.to_prompt_string()`
to serialize results for LLM prompts. Each `RecallResult` carries `.text`,
`.type_`, and optional `.context` and temporal fields.

### Reflect

Ask a higher-level question over everything the namespace knows. `budget`
defaults to `"low"`; the answer is on `.text`:

```python
answer = client.reflect(
    namespace_id="alice",
    query="Summarize Ada's recent work",
    include_facts=True,
)
print(answer.text)
```

Other keyword arguments: `context`, `max_tokens`, `response_schema` (a JSON
Schema — the response then includes `structured_output`), `tags`, `tags_match`,
`tag_groups`, `fact_types`, `exclude_automations`, and
`exclude_automation_ids`. `include_facts=True` adds a `based_on` field listing
the sources used.

## Error handling

Any non-success (>= 400) response raises `IlluminaAPIError`, which carries
`status_code`, `detail`, and the raw `content`:

```python
from illumina_client import Illumina, IlluminaAPIError

client = Illumina(base_url="https://api.illumina.sh", api_key="sub_live_...")

try:
    client.recall(namespace_id="missing", query="anything")
except IlluminaAPIError as err:
    print(err.status_code, err.detail)
```

## Method reference

Every method below exists in sync and async (`a`-prefixed) form.

### Retain

| Method | Description |
| --- | --- |
| [`retain`](/api-reference/memory#retain_memories) | Store a single memory. |
| [`retain_batch`](/api-reference/memory#retain_memories) | Store multiple memories in one request. |
| `retain_files` | Upload files and retain their contents; always asynchronous, returns operation IDs. |

### Recall

| Method | Description |
| --- | --- |
| [`recall`](/api-reference/memory#recall_memories) | Retrieve memories by semantic similarity. |

### Reflect

| Method | Description |
| --- | --- |
| [`reflect`](/api-reference/memory#reflect) | Generate a contextual answer from the namespace's identity and memories. |

### Memories

| Method | Description |
| --- | --- |
| [`list_memories`](/api-reference/memory#list_memories) | List memory units with pagination and filters. |
| `get_memory` | Get a single memory unit by ID. |
| `clear_memories` | Delete memory units, optionally filtered by fact type. Destructive and irreversible. |

### Namespaces

| Method | Description |
| --- | --- |
| [`create_namespace`](/api-reference/namespaces#create_or_update_namespace) | Create or update a namespace. |
| [`set_mission`](/api-reference/namespaces#create_or_update_namespace) | Set a namespace's mission (wrapper around `create_namespace`). |
| [`set_reflect_mission`](/api-reference/namespaces#create_or_update_namespace) | Set a namespace's reflect mission. |
| `delete_namespace` | Delete a namespace. |

### Namespace config

| Method | Description |
| --- | --- |
| `get_namespace_config` | Get the resolved configuration for a namespace. |
| `update_namespace_config` | Update config overrides, passed as keyword arguments. |
| `reset_namespace_config` | Reset all namespace-level overrides to server defaults. |

### Namespace templates

| Method | Description |
| --- | --- |
| `export_namespace_template` | Export config overrides, automations, and directives as a portable manifest. |
| `import_namespace_template` | Apply a template manifest; pass `dry_run=True` to validate without writing. |

### Automations

| Method | Description |
| --- | --- |
| `create_automation` | Create an automation (a reflect that runs in the background). |
| `list_automations` | List automations, optionally filtered by tags. |
| `get_automation` | Get a specific automation. |
| `refresh_automation` | Re-synthesize an automation with current knowledge. |
| `clear_automation` | Clear content so the next refresh performs a full re-synthesis. |
| `update_automation` | Update an automation's metadata. |
| `delete_automation` | Delete an automation. |
| `get_automation_history` | Get an automation's content change history. |

`create_automation` and `update_automation` accept a
`trigger_refresh_after_consolidation: bool` shortcut that expands to
`trigger={"refresh_after_consolidation": value}`; an explicit `trigger` dict
takes precedence.

### Directives

| Method | Description |
| --- | --- |
| `create_directive` | Create a directive (hard rule applied during reflect). |
| `list_directives` | List directives, optionally filtered by tags. |
| `get_directive` | Get a specific directive. |
| `update_directive` | Update a directive. |
| `delete_directive` | Delete a directive. |

### Documents

| Method | Description |
| --- | --- |
| `list_documents` | List documents with pagination and tag filters. |
| `get_document` | Get a specific document. |
| `update_document` | Update a document's tags (triggers re-consolidation). |
| `delete_document` | Delete a document and its derived memory units. |
| `get_document_chunks` | List a document's raw text chunks, ordered by index. |
| `reprocess_document` | Re-run the retain pipeline on an existing document. |

### Entities

| Method | Description |
| --- | --- |
| `get_entity_graph` | Get the entity co-occurrence graph for a namespace. |
| `classify_entities` | Backfill ontology classes onto unclassified entities. |

### Ontology

| Method | Description |
| --- | --- |
| `get_ontology` | Get entity classes, typed relations, and the resolved ontology mode. |
| `put_ontology` | Replace the namespace's ontology (whole-document). |
| `infer_ontology` | Propose a draft ontology from the entity graph. |
| `get_ontology_infer_status` | Poll the inference lifecycle; the stored draft is inline when ready. |

### Communities

| Method | Description |
| --- | --- |
| `build_communities` | Rebuild communities from the entity co-occurrence graph (background by default). |
| `list_communities` | List communities, largest first, with build status attached. |
| `get_community` | Get one community, including its member entities. |
| `get_community_status` | Get the build lifecycle and live community count. |
| `clear_communities` | Delete all communities and reset the build state. |

### Audit

| Method | Description |
| --- | --- |
| `list_audit_logs` | List audit log entries with filters and pagination. |
| `audit_stats` | Get audit log counts grouped by time bucket. |

### Beyond the wrapper

For operations without a convenience method (async operations, webhooks,
monitoring, remaining entity ops), use the per-group accessors, which pre-bind
the low-level client:

```python
client.documents.delete_document.sync(namespace_id, document_id)
await client.operations.get_operation_status.asyncio(namespace_id, op_id)
```

Available groups: `memory`, `namespaces`, `documents`, `entities`,
`automations`, `directives`, `operations`, `webhooks`, `files`, `monitoring`,
`audit`, `communities`, `ontology`, and `namespace_templates`. Each operation
exposes `sync`, `sync_detailed`, `asyncio`, and `asyncio_detailed`.

===/sdks/typescript===

# TypeScript SDK

Install and use @illumina/client, the TypeScript SDK for the Illumina API.

The TypeScript SDK is published as `@illumina/client`. Its `IlluminaClient`
class wraps every common operation and runs in Node.js, Bun, Deno, and the
browser (it uses the fetch API). All methods are `async`, take `namespaceId` as
the first argument, and accept an optional `signal` (an `AbortSignal`) inside
their options object.

## Install

```bash
npm install @illumina/client
```

## Initialize

Construct the client with the hosted base URL and your API key. The key is sent
as a bearer token on every request:

```typescript
import { IlluminaClient } from "@illumina/client";

const client = new IlluminaClient({
  baseUrl: "https://api.illumina.sh",
  apiKey: "sub_live_...",
});
```

| Option | Description |
| --- | --- |
| `baseUrl` | Required. The API base URL — `https://api.illumina.sh` for the hosted service. |
| `apiKey` | Your `sub_live_...` key, sent as `Authorization: Bearer <key>`. |
| `userAgent` | Overrides the default `illumina-client-typescript/<version>` header. Node.js, Bun, and Deno only — browsers ignore it. |

## Core operations

Memories live in namespaces, and retain does not auto-create one — create it
first:

```typescript
await client.createNamespace("alice");
```

### Retain

Store raw text; Illumina extracts facts, entities, and relationships.
`retain(namespaceId, content, options?)`:

```typescript
await client.retain("alice", "Ada shipped the payments rewrite in Q3 2025.", {
  context: "standup notes",
  tags: ["work"],
});
```

Options: `timestamp`, `context`, `metadata`, `documentId`, `async`, `entities`,
`tags`, `updateMode` (`"replace"` | `"append"`), `observationScopes`,
`strategy`, and `factType` (`"world"` | `"experience"` | `"decision"`).

Use `retainBatch(namespaceId, items, options?)` for multiple memories in one
request — each item requires `content`:

```typescript
await client.retainBatch("alice", [
  { content: "Alice loves hiking" },
  { content: "Alice visited Paris", context: "travel", timestamp: "2024-07-01" },
], { async: true });
```

`retainFiles(namespaceId, files, options?)` takes an `Array<File | Blob>` plus
`context` or `filesMetadata`, always processes asynchronously, and returns
operation IDs for tracking progress.

### Recall

Query a namespace by semantic similarity. `recall(namespaceId, query,
options?)` — `budget` (`"low"` | `"mid"` | `"high"`) controls retrieval effort
and defaults to `"mid"`:

```typescript
const recalled = await client.recall("alice", "What are Alice's hobbies?", {
  budget: "mid",
  includeEntities: true,
});
for (const result of recalled.results) {
  console.log(result.text);
}
```

Other options: `types` (filter by fact type), `maxTokens`, `tags` and
`tagsMatch` (`"any"` | `"all"` | `"any_strict"` | `"all_strict"`), `tagGroups`
(compound boolean tag filters, mutually exclusive with `tags`/`tagsMatch`),
`includeChunks`, `includeSourceFacts`, `queryTimestamp`, and `trace`.

`recall` returns a `RecallResponse` whose facts live on `.results` (not a bare
array). The exported helper `recallResponseToPromptString(response)`
serializes a response into a string for LLM prompts.

### Reflect

Ask a higher-level question over everything the namespace knows.
`reflect(namespaceId, query, options?)` — `budget` defaults to `"low"`; the
answer is on `.text`:

```typescript
const answer = await client.reflect("alice", "Summarize Ada's recent work", {
  factTypes: ["world", "observation"],
});
console.log(answer.text);
```

Other options: `context`, `maxTokens`, `responseSchema` (a JSON Schema — the
response then includes `structured_output`), `tags`, `tagsMatch`, `tagGroups`,
`excludeAutomations`, and `excludeAutomationIds`.

## Error handling

Failed requests throw an `IlluminaError` carrying `statusCode` and `details`:

```typescript
import { IlluminaClient, IlluminaError } from "@illumina/client";

try {
  await client.recall("missing", "anything");
} catch (err) {
  if (err instanceof IlluminaError) {
    console.error(err.statusCode, err.details);
  }
}
```

## Method reference

### Retain

| Method | Description |
| --- | --- |
| [`retain`](/api-reference/memory#retain_memories) | Store a single memory. |
| [`retainBatch`](/api-reference/memory#retain_memories) | Store multiple memories in one request. |
| `retainFiles` | Upload files and retain their contents; always asynchronous, returns operation IDs. |

### Recall

| Method | Description |
| --- | --- |
| [`recall`](/api-reference/memory#recall_memories) | Retrieve memories by semantic similarity. |

### Reflect

| Method | Description |
| --- | --- |
| [`reflect`](/api-reference/memory#reflect) | Generate a contextual answer from the namespace's identity and memories. |

### Memories

| Method | Description |
| --- | --- |
| [`listMemories`](/api-reference/memory#list_memories) | List memory units with pagination and filters. |

### Namespaces

| Method | Description |
| --- | --- |
| [`createNamespace`](/api-reference/namespaces#create_or_update_namespace) | Create or update a namespace. |
| [`setMission`](/api-reference/namespaces#create_or_update_namespace) | Deprecated — forwards to `createNamespace({ reflectMission })`. |
| `getNamespaceProfile` | Get a namespace's profile. |
| `deleteNamespace` | Delete a namespace. |

The `createNamespace` disposition fields (`name`, `mission`, `background`,
`disposition*`) are deprecated in favour of `updateNamespaceConfig`.

### Namespace config

| Method | Description |
| --- | --- |
| `getNamespaceConfig` | Get the resolved configuration for a namespace. |
| `updateNamespaceConfig` | Update configuration overrides. |
| `resetNamespaceConfig` | Reset all namespace-level overrides to server defaults. |

### Automations

| Method | Description |
| --- | --- |
| `createAutomation` | Create an automation (runs reflect in the background). |
| `listAutomations` | List automations, optionally filtered by tags. |
| `getAutomation` | Get a specific automation. |
| `refreshAutomation` | Re-synthesize an automation with current knowledge. |
| `clearAutomation` | Clear content so the next refresh performs a full re-synthesis. |
| `updateAutomation` | Update an automation's metadata. |
| `deleteAutomation` | Delete an automation. |
| `getAutomationHistory` | Get an automation's change history. |

### Directives

| Method | Description |
| --- | --- |
| `createDirective` | Create a directive (hard rule for reflect). |
| `listDirectives` | List directives, optionally filtered by tags. |
| `getDirective` | Get a specific directive. |
| `updateDirective` | Update a directive. |
| `deleteDirective` | Delete a directive. |

### Documents

| Method | Description |
| --- | --- |
| `listDocuments` | List documents with pagination and tag filters. |
| `getDocument` | Get a document by ID; returns `null` if not found. |
| `updateDocument` | Update a document's mutable fields (tags). |
| `deleteDocument` | Delete a document. |

### Ontology

| Method | Description |
| --- | --- |
| `getOntology` | Get entity classes, typed relations, and the resolved ontology mode. |
| `putOntology` | Replace the namespace's ontology (whole-document). |
| `inferOntology` | Propose a draft ontology from the entity graph. |
| `getOntologyInferStatus` | Poll the inference lifecycle; the stored draft is inline when ready. |
| `classifyEntities` | Backfill ontology classes onto unclassified entities. |

### Communities

| Method | Description |
| --- | --- |
| `buildCommunities` | Rebuild communities from the entity co-occurrence graph (background by default). |
| `listCommunities` | List communities, largest first, with build status attached. |
| `getCommunity` | Get one community, including its member entities. |
| `getCommunityStatus` | Get the build lifecycle and live community count. |
| `clearCommunities` | Delete all communities and reset the build state. |

### Beyond the wrapper

The package re-exports the generated layer for any endpoint the wrapper does
not cover (entity graph, operations, webhooks, namespace templates,
monitoring):

```typescript
import { sdk, createClient, createConfig } from "@illumina/client";
```

Request and response types are exported from the package root as well (for
example `RecallResponse`, `ReflectResponse`, `RetainResponse`, `Budget`,
`MemoryItem`).

===/mcp/overview===

# MCP server

Give Claude, Cursor, or any MCP client direct access to Illumina memory tools.

Illumina exposes its full memory surface over the
[Model Context Protocol](https://modelcontextprotocol.io). Connect an MCP
client — Claude Code, Claude Desktop, Cursor, or anything that speaks MCP —
and the agent gets first-class tools for retaining, recalling, and reflecting
over long-term memory, no SDK integration required.

The server is hosted at `api.illumina.sh` and authenticates with the same
`sub_live_...` API keys as the REST API. See [MCP setup](/mcp/setup) for
connection details.

## The tool surface

The server registers 36 tools covering every core operation:

| Group | Tools |
| --- | --- |
| Core | `retain`, `sync_retain`, `recall`, `reflect` |
| Namespaces | `list_namespaces`, `create_namespace`, `get_namespace`, `get_namespace_stats`, `update_namespace`, `delete_namespace` |
| Memories | `list_memories`, `get_memory`, `clear_memories` |
| Documents | `list_documents`, `get_document`, `delete_document` |
| Automations | `list_automations`, `get_automation`, `create_automation`, `update_automation`, `delete_automation`, `refresh_automation`, `clear_automation` |
| Directives | `list_directives`, `create_directive`, `delete_directive` |
| Communities | `list_communities`, `get_community`, `build_communities`, `get_community_status`, `clear_communities` |
| Ontology | `get_ontology` |
| Operations | `list_operations`, `get_operation`, `cancel_operation` |
| Tags | `list_tags` |

The four core tools mirror the REST memory operations: `retain` writes
asynchronously and returns an operation id, `sync_retain` blocks until the
memory is recallable, `recall` runs fused semantic/lexical/graph/temporal
search, and `reflect` synthesizes a reasoned answer across everything the
namespace knows.

Connecting to a specific namespace endpoint exposes 33 of the 36 tools — the
namespace-discovery tools (`list_namespaces`, `create_namespace`,
`get_namespace_stats`) only appear in multi-namespace mode, where every tool
also accepts an optional `namespace_id` argument for cross-namespace
operations.

## Narrowing the tool set

Each namespace has an `mcp_enabled_tools` configuration field. When set, only
the listed tools are exposed to MCP clients connected to that namespace —
useful for read-only integrations (say, `recall` and `reflect` only) or for
keeping destructive tools like `delete_namespace` out of an agent's reach.
The field is managed through the namespace configuration REST API; the MCP
`update_namespace` tool cannot change it.

## Next steps

- [MCP setup](/mcp/setup) — connect Claude Code or another client.
- [MCP tools](/mcp/tools) — the full tool reference.

===/mcp/setup===

# MCP setup

Connect Claude Code, Cursor, or any MCP client to Illumina's hosted MCP server.

The hosted MCP server lives on the same domain as the REST API, speaks the
MCP HTTP transport, and authenticates with a `sub_live_...` API key. There is
nothing to install.

## HTTP transport

Point your client at a namespace-scoped endpoint:

```
https://api.illumina.sh/mcp/{namespace_id}
```

Authenticate every request with a bearer header:

```
Authorization: Bearer sub_live_...
```

This is single-namespace mode: all 33 namespace-scoped tools operate on
`{namespace_id}`, and the namespace-discovery tools are hidden.

### Claude Code

Add the server to `.mcp.json` in your project root:

```json title=".mcp.json"
{
  "mcpServers": {
    "illumina": {
      "type": "http",
      "url": "https://api.illumina.sh/mcp/demo",
      "headers": {
        "Authorization": "Bearer sub_live_..."
      }
    }
  }
}
```

Restart Claude Code and the Illumina tools appear alongside the built-in
tools. Ask it to "remember" something and it will call `retain`; ask what it
knows and it will call `recall` or `reflect`.

### Other clients

Any MCP client that supports the HTTP transport works the same way: set the
URL to `https://api.illumina.sh/mcp/{namespace_id}` and pass the
`Authorization: Bearer sub_live_...` header. The server answers JSON-RPC
POSTs and responds to GET with a liveness probe.

## Multi-namespace mode

To work across several namespaces from one connection, use the bare endpoint:

```
https://api.illumina.sh/mcp
```

Set the default namespace for the session with a header:

```
X-Namespace-Id: demo
```

In multi-namespace mode all 36 tools are exposed, and every tool accepts an
optional `namespace_id` argument that overrides the session namespace per
call — so one connection can retain into `agent-alpha` and recall from
`agent-beta`, as long as the API key is scoped to both.

## Key scoping

API keys are scoped to namespaces at creation, and the MCP endpoints enforce
that scope on every call: connecting to a namespace outside the key's scope
is refused with `403`, and a per-call `namespace_id` override in
multi-namespace mode cannot escape the scope either. See
[Authentication](/docs/authentication) for key management.

> The MCP endpoints answer an out-of-scope namespace with `403 Forbidden`, which
> differs from the REST API's convention of hiding out-of-scope resources behind
> `404`. Handle both if your client talks to each surface.

## Next steps

- [MCP tools](/mcp/tools) — What each of the 36 tools does.
- [MCP server](/mcp/overview) — The tool surface at a glance.

===/mcp/tools===

# MCP tools

Reference for all 36 tools exposed by Illumina's MCP server.

The hosted MCP server exposes 36 tools, grouped below by area. Namespace-scoped
endpoints (`/mcp/{namespace_id}`) expose all of them except the three
namespace-discovery tools (`list_namespaces`, `create_namespace`,
`get_namespace_stats`), which only appear in
[multi-namespace mode](/mcp/setup#multi-namespace-mode). A namespace's
`mcp_enabled_tools` configuration can narrow the set further — see the
[overview](/mcp/overview#narrowing-the-tool-set).

In multi-namespace mode every tool also accepts an optional `namespace_id`
argument to target a namespace other than the session default.

## Core

| Tool | Description |
| --- | --- |
| `retain` | Store a fact or memory into long-term memory for later recall; storage is asynchronous and returns an operation id. |
| `sync_retain` | Store information to long-term memory and wait for completion, so the memory is immediately available for recall. |
| `recall` | Search long-term memory and return the most relevant facts for a query, fusing semantic, lexical, graph, and temporal retrieval. |
| `reflect` | Generate a synthesized, reasoned answer by reflecting across stored memories and the namespace's personality. |

## Namespaces

| Tool | Description |
| --- | --- |
| `list_namespaces` | List all available memory namespaces, each an isolated memory store with its own ID, name, disposition, and mission. |
| `create_namespace` | Create a new memory namespace or get an existing one. |
| `get_namespace` | Get the profile of a memory namespace, including its name, disposition, and mission. |
| `get_namespace_stats` | Get statistics for a memory namespace: counts of nodes, links, operations, documents, and consolidation metrics. |
| `update_namespace` | Update a memory namespace's display name or configuration fields; only provided fields are changed. |
| `delete_namespace` | Delete a memory namespace and all its data; this action cannot be undone. |

## Memories

| Tool | Description |
| --- | --- |
| `list_memories` | Browse stored memory units with optional filtering, without recall's relevance ranking. |
| `get_memory` | Get a specific memory unit by id, including content, metadata, and timestamps. |
| `clear_memories` | Clear all memories from a namespace without deleting the namespace itself, optionally filtered by fact type. |

## Documents

| Tool | Description |
| --- | --- |
| `list_documents` | List documents (containers grouping related memories) in a memory namespace. |
| `get_document` | Get a specific document by id, returning its metadata and associated memory information. |
| `delete_document` | Delete a document and all memories linked to it. |

## Automations

| Tool | Description |
| --- | --- |
| `list_automations` | List automations (pinned, refreshable reflections) for a memory namespace. |
| `get_automation` | Get a specific automation by id. |
| `create_automation` | Create an automation, a living document generated by running a source query through reflect. |
| `update_automation` | Update an automation's metadata: name, source query, tags, or max tokens. |
| `delete_automation` | Delete an automation and its generated content. |
| `refresh_automation` | Refresh an automation by re-running its source query through reflect (asynchronous). |
| `clear_automation` | Clear an automation's content so the next refresh performs a full re-synthesis. |

## Directives

| Tool | Description |
| --- | --- |
| `list_directives` | List directives (instructions that guide how the engine processes queries and reflects) for a memory namespace. |
| `create_directive` | Create a new directive that guides how the engine processes queries and generates reflections. |
| `delete_directive` | Delete a directive, permanently removing it from the memory namespace. |

## Communities

| Tool | Description |
| --- | --- |
| `list_communities` | List GraphRAG communities (thematic entity clusters with summaries) for a memory namespace. |
| `get_community` | Get one community by id, including its thematic summary and member entity names. |
| `build_communities` | Rebuild GraphRAG communities for a memory namespace from the entity co-occurrence graph. |
| `get_community_status` | Get community build status for a memory namespace: never, building, ready, or failed, plus last built time and count. |
| `clear_communities` | Delete all GraphRAG communities for a memory namespace, resetting build status so the next build starts from scratch. |

## Ontology

| Tool | Description |
| --- | --- |
| `get_ontology` | Get the memory namespace's ontology: entity classes and typed relations between classes. |

## Operations

| Tool | Description |
| --- | --- |
| `list_operations` | List async operations that track background tasks like retain processing and automation refresh. |
| `get_operation` | Get the status of an async operation. |
| `cancel_operation` | Cancel a pending async operation that has not yet started. |

## Tags

| Tool | Description |
| --- | --- |
| `list_tags` | List tags used in a memory namespace with usage counts. |

===/api-reference===

# API reference

Base URL, conventions, and how the reference is organized.

The Illumina REST API lives at:

```
https://api.illumina.sh
```

Every endpoint authenticates with `Authorization: Bearer sub_live_...` — see
[Authentication](/docs/authentication). Requests and responses are JSON unless
noted (file upload is multipart).

## Conventions

- **Paths** follow `/v1/default/namespaces/{namespace_id}/...`. The `default`
  segment is a fixed literal; workspace identity comes from your API key.
- **Asynchronous writes**: retain and file retain return an `operation_id`
  and process in the background. Track progress on
  [Async operations](/api-reference/operations).
- **Budgets**: recall and reflect take `budget` (`low`, `mid`, `high`) to
  trade latency for retrieval depth.
- **Errors** share one envelope and status vocabulary — see
  [Errors](/docs/errors). Rate limits are described in
  [Rate limits](/docs/rate-limits).

## Sections

- [Memory](/api-reference/memory) — Retain, recall, reflect, decisions, tags, graph.
- [Namespaces](/api-reference/namespaces) — Lifecycle, config, consolidation, stats.
- [Documents](/api-reference/documents) — Documents behind memories, chunks, reprocessing.
- [Files](/api-reference/files) — File upload for OCR and retention.
- [Automations](/api-reference/automations) — Standing reflect queries that stay current.
- [Directives](/api-reference/directives) — Standing instructions steering retain and recall.
- [Entities](/api-reference/entities) — Extracted entities and the entity graph.
- [Communities](/api-reference/communities) — Clusters of related memories.
- [Ontology](/api-reference/ontology) — Entity and relationship type system.
- [Async operations](/api-reference/operations) — Operation status, retry, cancel.
- [Compilation](/api-reference/compilation) — Promotion triggers and sweeps.
- [Webhooks](/api-reference/webhooks) — Signed event delivery.
- [Audit logs](/api-reference/audit) — Recall and MCP activity trail.
- [Namespace templates](/api-reference/namespace-templates) — Export and import namespace configuration.
- [Monitoring](/api-reference/monitoring) — Health and version.

===/api-reference/memory===

# Memory API

Retain, recall, and reflect — plus memory listing, decisions, tags, and the knowledge graph.

## Retain memories

`POST /v1/default/namespaces/{namespace_id}/memories`

Retain memory items with automatic fact extraction.

This is the main endpoint for storing memories. It supports both synchronous and asynchronous processing via the `async` parameter.

**Features:**
- Efficient batch processing
- Automatic fact extraction from natural language
- Entity recognition and linking
- Document tracking with automatic upsert (when document_id is provided)
- Temporal and semantic linking
- Optional asynchronous processing

**The system automatically:**
1. Extracts semantic facts from the content
2. Generates embeddings
3. Deduplicates similar facts
4. Creates temporal, semantic, and entity links
5. Tracks document metadata

**When `async=true`:** Returns immediately after queuing. Use the operations endpoint to monitor progress.

**When `async=false` (default):** Waits for processing to complete.

**Note:** If a memory item has a `document_id` that already exists, the old document and its memory units will be deleted before creating new ones (upsert behavior).

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/memories" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "content": "Ada shipped the payments rewrite in Q3 2025."
    }
  ]
}'
```

Example response:

```json
{
  "async": false,
  "namespace_id": "user123",
  "items_count": 2,
  "success": true,
  "usage": {
    "input_tokens": 500,
    "output_tokens": 100,
    "total_tokens": 600
  }
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Recall memory

`POST /v1/default/namespaces/{namespace_id}/memories/recall`

Recall memory using semantic similarity and spreading activation.

The type parameter is optional and must be one of:
- `world`: General knowledge about people, places, events, and things that happen
- `experience`: Memories about experience, conversations, actions taken, and tasks performed

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/memories/recall" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "who shipped payments?",
  "budget": "mid",
  "max_tokens": 2048
}'
```

Example response:

```json
{
  "chunks": {
    "456e7890-e12b-34d5-a678-901234567890": {
      "chunk_index": 0,
      "id": "456e7890-e12b-34d5-a678-901234567890",
      "text": "Alice works at Google on the AI team. She's been there for 3 years..."
    }
  },
  "entities": {
    "Alice": {
      "canonical_name": "Alice",
      "entity_id": "123e4567-e89b-12d3-a456-426614174001",
      "observations": [
        {
          "mentioned_at": "2024-01-15T10:30:00Z",
          "text": "Alice works at Google on the AI team"
        }
      ]
    }
  },
  "results": [
    {
      "chunk_id": "456e7890-e12b-34d5-a678-901234567890",
      "context": "work info",
      "entities": [
        "Alice",
        "Google"
      ],
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "occurred_end": "2024-01-15T10:30:00Z",
      "occurred_start": "2024-01-15T10:30:00Z",
      "text": "Alice works at Google on the AI team",
      "type": "world"
    }
  ],
  "trace": {
    "num_results": 1,
    "query": "What did Alice say about machine learning?",
    "time_seconds": 0.123
  }
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Reflect and generate answer

`POST /v1/default/namespaces/{namespace_id}/reflect`

Reflect and formulate an answer using namespace identity, world facts, and opinions.

This endpoint:
1. Retrieves experience (conversations and events)
2. Retrieves world facts relevant to the query
3. Retrieves existing opinions (namespace's perspectives)
4. Uses LLM to formulate a contextual answer
5. Returns plain text answer and the facts used

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/reflect" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "summarize Ada'\''s recent work",
  "budget": "low",
  "max_tokens": 512
}'
```

Example response:

```json
{
  "based_on": {
    "memories": [
      {
        "id": "123",
        "text": "AI is used in healthcare",
        "type": "world"
      },
      {
        "id": "456",
        "text": "I discussed AI applications last week",
        "type": "experience"
      }
    ]
  },
  "structured_output": {
    "key_points": [
      "Used in healthcare",
      "Discussed recently"
    ],
    "summary": "AI is transformative"
  },
  "text": "## AI Overview\n\nBased on my understanding, AI is a **transformative technology**:\n\n- Used extensively in healthcare\n- Discussed in recent conversations\n- Continues to evolve rapidly",
  "trace": {
    "llm_calls": [
      {
        "duration_ms": 1200,
        "scope": "agent_1"
      }
    ],
    "observations": [
      {
        "id": "obs-1",
        "name": "AI Technology",
        "subtype": "structural",
        "type": "concept"
      }
    ],
    "tool_calls": [
      {
        "duration_ms": 150,
        "input": {
          "query": "AI"
        },
        "tool": "recall"
      }
    ]
  },
  "usage": {
    "input_tokens": 1500,
    "output_tokens": 500,
    "total_tokens": 2000
  }
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## List memory units

`GET /v1/default/namespaces/{namespace_id}/memories/list`

List memory units with pagination and optional full-text search. Supports filtering by type. Results are sorted by most recent first (mentioned_at DESC, then created_at DESC).

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `type` | query | "world" | "experience" | "observation" | "decision" | no |  |
| `q` | query | string | null | no |  |
| `consolidation_state` | query | string | null | no |  |
| `status` | query | "standing" | "superseded" | no |  |
| `order` | query | "asc" | "desc" | no |  |
| `since` | query | string (date-time) | null | no |  |
| `until` | query | string (date-time) | null | no |  |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |

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

Example response:

```json
{
  "items": [
    {
      "context": "Work conversation",
      "date": "2024-01-15T10:30:00Z",
      "entities": "Alice (PERSON), Google (ORGANIZATION)",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "text": "Alice works at Google on the AI team",
      "type": "world"
    }
  ],
  "limit": 100,
  "offset": 0,
  "total": 150
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get memory unit

`GET /v1/default/namespaces/{namespace_id}/memories/{memory_id}`

Get a single memory unit by ID with all its metadata including entities and tags. Note: the 'history' field is deprecated and always returns an empty list - use GET /memories/{memory_id}/history instead.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `memory_id` | path | string | yes |  |

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

Example response:

```json
null
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Clear memory namespace memories

`DELETE /v1/default/namespaces/{namespace_id}/memories`

Delete memory units for a memory namespace. Optionally filter by type (world, experience, observation, decision) to delete only specific types. This is a destructive operation that cannot be undone. The namespace profile (disposition and background) will be preserved.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `type` | query | string | null | no | Optional fact type filter (world, experience, observation, decision) |

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

Example response:

```json
{
  "deleted_count": 10,
  "message": "Deleted successfully",
  "success": true
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## List tags

`GET /v1/default/namespaces/{namespace_id}/tags`

List all unique tags in a memory namespace with usage counts. Supports wildcard search using '*' (e.g., 'user:*', '*-fred', 'tag*-2'). Case-insensitive. Use `source=automations` to list tags used on automations instead of memories.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `q` | query | string | null | no | Wildcard pattern to filter tags (e.g., 'user:*' for user:alice, '*-admin' for role-admin). Use '*' as wildcard. Case-insensitive. |
| `source` | query | "memories" | "automations" | no | Where to read tags from: 'memories' (memory_units, default) or 'automations'. |
| `limit` | query | integer | no | Maximum number of tags to return |
| `offset` | query | integer | no | Offset for pagination |

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

Example response:

```json
{
  "items": [
    {
      "count": 42,
      "tag": "user:alice"
    },
    {
      "count": 15,
      "tag": "user:bob"
    },
    {
      "count": 8,
      "tag": "session:abc123"
    }
  ],
  "limit": 100,
  "offset": 0,
  "total": 25
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get memory graph data

`GET /v1/default/namespaces/{namespace_id}/graph`

Retrieve graph data for visualization, optionally filtered by type (world/experience/observation/decision).

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `type` | query | string | null | no |  |
| `limit` | query | integer | no |  |
| `q` | query | string | null | no |  |
| `tags` | query | string[] | no |  |
| `tags_match` | query | string | no |  |
| `document_id` | query | string | null | no |  |
| `chunk_id` | query | string | null | no |  |

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

Example response:

```json
{
  "edges": [
    {
      "from": "1",
      "to": "2",
      "type": "semantic",
      "weight": 0.8
    }
  ],
  "limit": 1000,
  "nodes": [
    {
      "id": "1",
      "label": "Alice works at Google",
      "type": "world"
    },
    {
      "id": "2",
      "label": "Bob went hiking",
      "type": "world"
    }
  ],
  "table_rows": [
    {
      "context": "Work info",
      "date": "2024-01-15 10:30",
      "entities": "Alice (PERSON), Google (ORGANIZATION)",
      "id": "abc12345...",
      "text": "Alice works at Google"
    }
  ],
  "total_units": 2
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Reconcile standing decisions

`POST /v1/default/namespaces/{namespace_id}/decisions/reconcile`

On-demand sweep pairing the namespace's standing decisions and marking supersessions retain-time detection missed. Capped per invocation; repeated calls converge. Billable LLM pairing.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/decisions/reconcile" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
null
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Supersede a decision

`POST /v1/default/namespaces/{namespace_id}/memories/{memory_id}/supersede`

Manually mark a standing decision as superseded by another standing decision. Writes the same supersedes link, metadata, and history event as retain-time detection, with source "manual".

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `memory_id` | path | string | yes |  |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/memories/mem_123/supersede" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "superseded_by": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b"
}'
```

Example response:

```json
null
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Revive a decision

`DELETE /v1/default/namespaces/{namespace_id}/memories/{memory_id}/supersede`

Undo a supersession: restore the decision to standing (lifecycle metadata keys are removed), delete the incoming supersedes link, and append a revived history event.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `memory_id` | path | string | yes |  |

```bash
curl -X DELETE "https://api.illumina.sh/v1/default/namespaces/demo/memories/mem_123/supersede" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
null
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get decision lineage

`GET /v1/default/namespaces/{namespace_id}/memories/{memory_id}/lineage`

Walk the supersession chain through a memory unit, both directions, returning the ordered chain (newest first), the standing head, and optionally which decision was standing at `as_of`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `memory_id` | path | string | yes |  |
| `as_of` | query | string (date-time) | null | no |  |

```bash
curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/memories/mem_123/lineage" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
null
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get observation history

`GET /v1/default/namespaces/{namespace_id}/memories/{memory_id}/history`

Get the full history of an observation, with each change's source facts resolved to their text.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `memory_id` | path | string | yes |  |

```bash
curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/memories/mem_123/history" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
null
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Clear observations for a memory

`DELETE /v1/default/namespaces/{namespace_id}/memories/{memory_id}/observations`

Delete all observations derived from a specific memory and reset it for re-consolidation. The memory itself is not deleted. A consolidation job is triggered automatically so the memory will produce fresh observations on the next consolidation run.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `memory_id` | path | string | yes |  |

```bash
curl -X DELETE "https://api.illumina.sh/v1/default/namespaces/demo/memories/mem_123/observations" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "deleted_count": 3
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

===/api-reference/namespaces===

# Namespaces API

Create and manage memory namespaces, their configuration, consolidation, and stats.

## List all memory namespaces

`GET /v1/default/namespaces`

Get a list of all agents with their profiles

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

Example response:

```json
{
  "namespaces": [
    {
      "namespace_id": "user123",
      "created_at": "2024-01-15T10:30:00Z",
      "disposition": {
        "empathy": 3,
        "literalism": 3,
        "skepticism": 3
      },
      "fact_count": 156,
      "last_document_at": "2024-01-16T14:20:00Z",
      "mission": "I am a software engineer helping my team ship quality code",
      "name": "Alice",
      "updated_at": "2024-01-16T14:20:00Z"
    }
  ]
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Create or update memory namespace

`PUT /v1/default/namespaces/{namespace_id}`

Create a new agent or update existing agent with disposition and mission. Auto-fills missing fields with defaults.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X PUT "https://api.illumina.sh/v1/default/namespaces/demo" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Example response:

```json
{
  "namespace_id": "user123",
  "disposition": {
    "empathy": 3,
    "literalism": 3,
    "skepticism": 3
  },
  "mission": "I am a software engineer helping my team stay organized and ship quality code",
  "name": "Alice"
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Partial update memory namespace

`PATCH /v1/default/namespaces/{namespace_id}`

Partially update an agent's profile. Only provided fields will be updated.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X PATCH "https://api.illumina.sh/v1/default/namespaces/demo" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "observations_mission": "Observations are stable facts about people and projects. Always include preferences and skills.",
  "retain_mission": "Always include technical decisions and architectural trade-offs. Ignore meeting logistics."
}'
```

Example response:

```json
{
  "namespace_id": "user123",
  "disposition": {
    "empathy": 3,
    "literalism": 3,
    "skepticism": 3
  },
  "mission": "I am a software engineer helping my team stay organized and ship quality code",
  "name": "Alice"
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Delete memory namespace

`DELETE /v1/default/namespaces/{namespace_id}`

Delete an entire memory namespace including all memories, entities, documents, and the namespace profile itself. This is a destructive operation that cannot be undone.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

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

Example response:

```json
{
  "deleted_count": 10,
  "message": "Deleted successfully",
  "success": true
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Add/merge memory namespace background (deprecated)

`POST /v1/default/namespaces/{namespace_id}/background`

**Deprecated.**

Deprecated: Use PUT /mission instead. This endpoint now updates the mission field.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/background" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "I was born in Texas",
  "update_disposition": true
}'
```

Example response:

```json
{
  "mission": "I was born in Texas. I am a software engineer with 10 years of experience."
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get namespace configuration

`GET /v1/default/namespaces/{namespace_id}/config`

Get fully resolved configuration for a namespace including all hierarchical overrides (global → tenant → namespace). The 'config' field contains all resolved config values. The 'overrides' field shows only namespace-specific overrides.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

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

Example response:

```json
{
  "namespace_id": "my-namespace",
  "config": {
    "llm_model": "gpt-4",
    "llm_provider": "openai",
    "retain_extraction_mode": "verbose"
  },
  "overrides": {
    "llm_model": "gpt-4",
    "retain_extraction_mode": "verbose"
  }
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Update namespace configuration

`PATCH /v1/default/namespaces/{namespace_id}/config`

Update configuration overrides for a namespace. Only hierarchical fields can be overridden (LLM settings, retention parameters, etc.). Keys can be provided in Python field format (llm_provider) or environment variable format (ILLUMINA_API_LLM_PROVIDER).

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X PATCH "https://api.illumina.sh/v1/default/namespaces/demo/config" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {
    "llm_model": "claude-sonnet-4-5",
    "retain_custom_instructions": "Extract technical details carefully",
    "retain_extraction_mode": "verbose"
  }
}'
```

Example response:

```json
{
  "namespace_id": "my-namespace",
  "config": {
    "llm_model": "gpt-4",
    "llm_provider": "openai",
    "retain_extraction_mode": "verbose"
  },
  "overrides": {
    "llm_model": "gpt-4",
    "retain_extraction_mode": "verbose"
  }
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Reset namespace configuration

`DELETE /v1/default/namespaces/{namespace_id}/config`

Reset namespace configuration to defaults by removing all namespace-specific overrides. The namespace will then use global and tenant-level configuration only.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

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

Example response:

```json
{
  "namespace_id": "my-namespace",
  "config": {
    "llm_model": "gpt-4",
    "llm_provider": "openai",
    "retain_extraction_mode": "verbose"
  },
  "overrides": {
    "llm_model": "gpt-4",
    "retain_extraction_mode": "verbose"
  }
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Trigger consolidation

`POST /v1/default/namespaces/{namespace_id}/consolidate`

Run memory consolidation to create/update observations from recent memories.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/consolidate" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "observation_scopes": [
    [
      "observation scopes"
    ]
  ]
}'
```

Example response:

```json
{
  "operation_id": "ope_123"
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Recover failed consolidation

`POST /v1/default/namespaces/{namespace_id}/consolidation/recover`

Reset all memories that were permanently marked as failed during consolidation (after exhausting all LLM retries and adaptive batch splitting) so they are picked up again on the next consolidation run. Does not delete any observations.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/consolidation/recover" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "retried_count": 42
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Clear all observations

`DELETE /v1/default/namespaces/{namespace_id}/observations`

Delete all observations for a memory namespace. This is useful for resetting the consolidated knowledge.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

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

Example response:

```json
{
  "deleted_count": 10,
  "message": "Deleted successfully",
  "success": true
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get memory namespace profile

`GET /v1/default/namespaces/{namespace_id}/profile`

**Deprecated.**

Get disposition traits and mission for a memory namespace. Returns 404 if the namespace does not exist.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

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

Example response:

```json
{
  "namespace_id": "user123",
  "disposition": {
    "empathy": 3,
    "literalism": 3,
    "skepticism": 3
  },
  "mission": "I am a software engineer helping my team stay organized and ship quality code",
  "name": "Alice"
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Update memory namespace disposition

`PUT /v1/default/namespaces/{namespace_id}/profile`

**Deprecated.**

Update namespace's disposition traits (skepticism, literalism, empathy)

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X PUT "https://api.illumina.sh/v1/default/namespaces/demo/profile" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "disposition": {
    "empathy": 3,
    "literalism": 3,
    "skepticism": 3
  }
}'
```

Example response:

```json
{
  "namespace_id": "user123",
  "disposition": {
    "empathy": 3,
    "literalism": 3,
    "skepticism": 3
  },
  "mission": "I am a software engineer helping my team stay organized and ship quality code",
  "name": "Alice"
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get statistics for memory namespace

`GET /v1/default/namespaces/{namespace_id}/stats`

Get statistics about nodes and links for a specific agent

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

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

Example response:

```json
{
  "namespace_id": "user123",
  "failed_consolidation": 0,
  "failed_operations": 0,
  "last_consolidated_at": "2024-01-15T10:30:00Z",
  "links_breakdown": {
    "fact": {
      "entity": 40,
      "semantic": 60,
      "temporal": 100
    }
  },
  "links_by_fact_type": {
    "fact": 200,
    "observation": 40,
    "preference": 60
  },
  "links_by_link_type": {
    "entity": 50,
    "semantic": 100,
    "temporal": 150
  },
  "nodes_by_fact_type": {
    "fact": 100,
    "observation": 20,
    "preference": 30
  },
  "pending_consolidation": 0,
  "pending_operations": 2,
  "total_documents": 10,
  "total_links": 300,
  "total_nodes": 150,
  "total_observations": 45
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Memory ingestion time-series

`GET /v1/default/namespaces/{namespace_id}/stats/memories-timeseries`

Memories ingested over a period, bucketed by time and broken down by fact type.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `period` | query | string | no |  |
| `time_field` | query | string | no | Timestamp column to bucket on. `created_at` (default) = ingest time; `mentioned_at` / `occurred_start` = event time, useful for migrated corpora where ingest time is a single point and doesn't reflect the underlying knowledge timeline. Unknown values fall back to `created_at`. |

```bash
curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/stats/memories-timeseries" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "namespace_id": "demo",
  "period": "period",
  "trunc": "trunc"
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

===/api-reference/documents===

# Documents API

List, inspect, update, and reprocess the documents behind retained memories.

## Get chunk details

`GET /v1/default/chunks/{chunk_id}`

Get a specific chunk by its ID

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `chunk_id` | path | string | yes |  |

```bash
curl -X GET "https://api.illumina.sh/v1/default/chunks/chu_123" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "namespace_id": "user123",
  "chunk_id": "user123_session_1_0",
  "chunk_index": 0,
  "chunk_text": "This is the first chunk of the document...",
  "created_at": "2024-01-15T10:30:00Z",
  "document_id": "session_1"
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## List documents

`GET /v1/default/namespaces/{namespace_id}/documents`

List documents with pagination and optional search. Documents are the source content from which memory units are extracted.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `q` | query | string | null | no | Case-insensitive substring filter on document ID (e.g. 'report' matches 'report-2024') |
| `tags` | query | string[] | no | Filter documents by tags |
| `tags_match` | query | string | no | How to match tags: 'any', 'all', 'any_strict', 'all_strict' |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |

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

Example response:

```json
{
  "items": [
    {
      "namespace_id": "user123",
      "content_hash": "abc123",
      "created_at": "2024-01-15T10:30:00Z",
      "id": "session_1",
      "memory_unit_count": 15,
      "tags": [
        "user_a",
        "session_123"
      ],
      "text_length": 5420,
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "limit": 100,
  "offset": 0,
  "total": 50
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get document details

`GET /v1/default/namespaces/{namespace_id}/documents/{document_id}`

Get a specific document including its original text

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `document_id` | path | string | yes |  |

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

Example response:

```json
{
  "namespace_id": "user123",
  "content_hash": "abc123",
  "created_at": "2024-01-15T10:30:00Z",
  "document_metadata": {
    "channel": "#general",
    "source": "slack"
  },
  "id": "session_1",
  "memory_unit_count": 15,
  "original_text": "Full document text here...",
  "retain_params": {
    "context": "Team meeting notes",
    "event_date": "2024-01-15"
  },
  "tags": [
    "user_a",
    "session_123"
  ],
  "updated_at": "2024-01-15T10:30:00Z"
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Update document

`PATCH /v1/default/namespaces/{namespace_id}/documents/{document_id}`

Update mutable fields on a document without re-processing its content.

**Tags** (`tags`): Propagated to all associated memory units. Observations derived from those units are invalidated and queued for re-consolidation under the new tags. Co-source memories from other documents that shared those observations are also reset.

At least one field must be provided.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `document_id` | path | string | yes |  |

```bash
curl -X PATCH "https://api.illumina.sh/v1/default/namespaces/demo/documents/doc_123" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tags": [
    "team-a",
    "team-b"
  ]
}'
```

Example response:

```json
{
  "success": true
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Delete a document

`DELETE /v1/default/namespaces/{namespace_id}/documents/{document_id}`

Delete a document and all its associated memory units and links.

This will cascade delete:
- The document itself
- All memory units extracted from this document
- All links (temporal, semantic, entity) associated with those memory units

This operation cannot be undone.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `document_id` | path | string | yes |  |

```bash
curl -X DELETE "https://api.illumina.sh/v1/default/namespaces/demo/documents/doc_123" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "document_id": "session_1",
  "memory_units_deleted": 5,
  "message": "Document 'session_1' and 5 associated memory units deleted successfully",
  "success": true
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## List document chunks

`GET /v1/default/namespaces/{namespace_id}/documents/{document_id}/chunks`

List all chunks for a given document, ordered by chunk index.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `document_id` | path | string | yes |  |
| `limit` | query | integer | no | Maximum number of chunks to return |
| `offset` | query | integer | no | Offset for pagination |

```bash
curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/documents/doc_123/chunks" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "items": [
    {
      "namespace_id": "user123",
      "chunk_id": "user123_session_1_0",
      "chunk_index": 0,
      "chunk_text": "This is the first chunk of the document...",
      "created_at": "2024-01-15T10:30:00Z",
      "document_id": "session_1"
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Reprocess document

`POST /v1/default/namespaces/{namespace_id}/documents/{document_id}/reprocess`

Re-run the retain pipeline on an existing document without changing its content. This deletes the existing memory units and re-extracts facts using the current engine configuration. Useful when the LLM model, chunking strategy, or extraction settings have changed.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `document_id` | path | string | yes |  |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/documents/doc_123/reprocess" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "success": false,
  "operation_id": "ope_123",
  "items_count": 1
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

===/api-reference/files===

# Files API

Upload files for OCR, parsing, and retention as memories.

## Convert files to memories

`POST /v1/default/namespaces/{namespace_id}/files/retain`

Upload files (PDF, DOCX, etc.), convert them to markdown, and retain as memories.

This endpoint handles file upload, conversion, and memory creation in a single operation.

**Features:**
- Supports PDF, DOCX, PPTX, XLSX, images (with OCR), audio (with transcription)
- Automatic file-to-markdown conversion using pluggable parsers
- Files stored in object storage (PostgreSQL by default, S3 for production)
- Each file becomes a separate document with optional metadata/tags
- Always processes asynchronously — returns operation IDs immediately

**The system automatically:**
1. Stores uploaded files in object storage
2. Converts files to markdown
3. Creates document records with file metadata
4. Extracts facts and creates memory units (same as regular retain)

Use the operations endpoint to monitor progress.

**Request format:** multipart/form-data with:
- `files`: One or more files to upload
- `request`: JSON string with FileRetainRequest model

**Parser selection:**
- Set `parser` in the request body to override the server default for all files.
- Set `parser` inside a `files_metadata` entry for per-file control.
- Pass a list (e.g. `['iris', 'markitdown']`) to define an ordered fallback chain — each parser is tried in sequence until one succeeds.
- Falls back to the server default (`ILLUMINA_API_FILE_PARSER`) if not specified.
- Only parsers enabled on the server may be requested; others return HTTP 400.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/files/retain" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -F "files=@notes.pdf"
```

Example response:

```json
{
  "operation_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002"
  ]
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

===/api-reference/automations===

# Automations API

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

## List automation templates

`GET /v1/default/automations/templates`

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

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

Example response:

```json
{}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410

## List automations

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

List user-curated living documents that stay current.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `tags` | query | string[] | no | Filter by tags |
| `tags_match` | query | "any" | "all" | "exact" | no | How to match tags |
| `detail` | query | "metadata" | "content" | "full" | no | Detail level: 'metadata' (names/tags only), 'content' (adds content/config), 'full' (includes reflect_response) |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |

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

Example response:

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

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Create automation

`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.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
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
  }
}'
```

Example response:

```json
{
  "operation_id": "ope_123"
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get automation

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

Get a specific automation by ID.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `automation_id` | path | string | yes |  |
| `detail` | query | "metadata" | "content" | "full" | no | Detail level: 'metadata' (names/tags only), 'content' (adds content/config), 'full' (includes reflect_response) |

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

Example response:

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

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Update automation

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

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `automation_id` | path | string | yes |  |

```bash
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
  }
}'
```

Example response:

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

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Delete automation

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

Delete an automation.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `automation_id` | path | string | yes |  |

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

Example response:

```json
null
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Clear automation content

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

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.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `automation_id` | path | string | yes |  |

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

Example response:

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

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get automation history

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

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `automation_id` | path | string | yes |  |

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

Example response:

```json
null
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Refresh automation

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

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `automation_id` | path | string | yes |  |

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

Example response:

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

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get automation run history

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

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.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `automation_id` | path | string | yes |  |

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

Example response:

```json
null
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

===/api-reference/directives===

# Directives API

Per-namespace standing instructions that steer retain and recall behavior.

## List directives

`GET /v1/default/namespaces/{namespace_id}/directives`

List hard rules that are injected into prompts.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `tags` | query | string[] | no | Filter by tags |
| `tags_match` | query | "any" | "all" | "exact" | no | How to match tags |
| `active_only` | query | boolean | no | Only return active directives |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |

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

Example response:

```json
{
  "items": [
    {
      "id": "ite_123",
      "namespace_id": "demo",
      "name": "Demo namespace",
      "content": "Ada shipped the payments rewrite in Q3 2025."
    }
  ]
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Create directive

`POST /v1/default/namespaces/{namespace_id}/directives`

Create a hard rule that will be injected into prompts.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/directives" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Demo namespace",
  "content": "Ada shipped the payments rewrite in Q3 2025."
}'
```

Example response:

```json
{
  "id": "ite_123",
  "namespace_id": "demo",
  "name": "Demo namespace",
  "content": "Ada shipped the payments rewrite in Q3 2025."
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get directive

`GET /v1/default/namespaces/{namespace_id}/directives/{directive_id}`

Get a specific directive by ID.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `directive_id` | path | string | yes |  |

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

Example response:

```json
{
  "id": "ite_123",
  "namespace_id": "demo",
  "name": "Demo namespace",
  "content": "Ada shipped the payments rewrite in Q3 2025."
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Update directive

`PATCH /v1/default/namespaces/{namespace_id}/directives/{directive_id}`

Update a directive's properties.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `directive_id` | path | string | yes |  |

```bash
curl -X PATCH "https://api.illumina.sh/v1/default/namespaces/demo/directives/dir_123" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Demo namespace",
  "content": "Ada shipped the payments rewrite in Q3 2025.",
  "priority": 1,
  "is_active": false
}'
```

Example response:

```json
{
  "id": "ite_123",
  "namespace_id": "demo",
  "name": "Demo namespace",
  "content": "Ada shipped the payments rewrite in Q3 2025."
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Delete directive

`DELETE /v1/default/namespaces/{namespace_id}/directives/{directive_id}`

Delete a directive.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `directive_id` | path | string | yes |  |

```bash
curl -X DELETE "https://api.illumina.sh/v1/default/namespaces/demo/directives/dir_123" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
null
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

===/api-reference/entities===

# Entities API

Entities extracted from memories and the graph that connects them.

## List entities

`GET /v1/default/namespaces/{namespace_id}/entities`

List all entities (people, organizations, etc.) known by the namespace, ordered by mention count. Supports pagination.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `limit` | query | integer | no | Maximum number of entities to return |
| `offset` | query | integer | no | Offset for pagination |

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

Example response:

```json
{
  "items": [
    {
      "canonical_name": "John",
      "first_seen": "2024-01-15T10:30:00Z",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "last_seen": "2024-02-01T14:00:00Z",
      "mention_count": 15
    }
  ],
  "limit": 100,
  "offset": 0,
  "total": 150
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get entity co-occurrence graph

`GET /v1/default/namespaces/{namespace_id}/entities/graph`

Return a graph of entities (nodes) and their co-occurrences (edges) for visualization.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `limit` | query | integer | no | Maximum number of co-occurrence edges to return |
| `min_count` | query | integer | no | Minimum cooccurrence_count to include an edge |

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

Example response:

```json
{
  "edges": [
    {
      "data": {
        "color": "#ffd700",
        "id": "uuid-1-uuid-2",
        "lastCooccurred": "2024-02-01T14:00:00Z",
        "lineStyle": "solid",
        "linkType": "cooccurrence",
        "source": "uuid-1",
        "target": "uuid-2",
        "weight": 5
      }
    }
  ],
  "limit": 1000,
  "nodes": [
    {
      "data": {
        "color": "#42a5f5",
        "id": "uuid-1",
        "label": "Alice",
        "mentionCount": 12
      }
    },
    {
      "data": {
        "color": "#42a5f5",
        "id": "uuid-2",
        "label": "Google",
        "mentionCount": 8
      }
    }
  ],
  "total_edges": 1,
  "total_entities": 2
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get entity details

`GET /v1/default/namespaces/{namespace_id}/entities/{entity_id}`

Get detailed information about an entity including observations (automation).

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `entity_id` | path | string | yes |  |

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

Example response:

```json
{
  "canonical_name": "John",
  "first_seen": "2024-01-15T10:30:00Z",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "last_seen": "2024-02-01T14:00:00Z",
  "mention_count": 15,
  "observations": [
    {
      "mentioned_at": "2024-01-15T10:30:00Z",
      "text": "John works at Google"
    }
  ]
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Regenerate entity observations (deprecated)

`POST /v1/default/namespaces/{namespace_id}/entities/{entity_id}/regenerate`

**Deprecated.**

This endpoint is deprecated. Entity observations have been replaced by automations.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `entity_id` | path | string | yes |  |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/entities/ent_123/regenerate" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "canonical_name": "John",
  "first_seen": "2024-01-15T10:30:00Z",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "last_seen": "2024-02-01T14:00:00Z",
  "mention_count": 15,
  "observations": [
    {
      "mentioned_at": "2024-01-15T10:30:00Z",
      "text": "John works at Google"
    }
  ]
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

===/api-reference/communities===

# Communities API

Clusters of related memories detected across the namespace graph.

## List communities

`GET /v1/default/namespaces/{namespace_id}/communities`

List GraphRAG communities for the namespace (largest first), with the build status attached. Supports pagination and a title/summary search.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `limit` | query | integer | no | Maximum number of communities to return |
| `offset` | query | integer | no | Offset for pagination |
| `q` | query | string | null | no | Case-insensitive title/summary search |

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

Example response:

```json
{
  "items": [
    {
      "id": "ite_123",
      "community_index": 1,
      "title": "title",
      "summary": "summary",
      "member_count": 1,
      "member_entity_ids": [
        "member entity ids"
      ],
      "member_names": [
        "member names"
      ]
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Clear communities

`DELETE /v1/default/namespaces/{namespace_id}/communities`

Delete all communities for the namespace and reset the build state to 'never'.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

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

Example response:

```json
{
  "deleted": 1,
  "status": "status"
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Build communities

`POST /v1/default/namespaces/{namespace_id}/communities/build`

Rebuild the namespace's communities from the entity co-occurrence graph. By default starts a background workflow (202); pass {"async": false} to build synchronously (200).

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/communities/build" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "async": true
}'
```

Example response:

```json
{
  "status": "status",
  "async": false
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get community build status

`GET /v1/default/namespaces/{namespace_id}/communities/status`

Namespace-level community build lifecycle: status, last build/start times, last error, and the live community count.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

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

Example response:

```json
{
  "status": "status",
  "communities_built": 1,
  "community_count": 1
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get community

`GET /v1/default/namespaces/{namespace_id}/communities/{community_id}`

Fetch one community by id, including its member entities.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `community_id` | path | string | yes |  |

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

Example response:

```json
{
  "id": "ite_123",
  "community_index": 1,
  "title": "title",
  "summary": "summary",
  "member_count": 1,
  "member_entity_ids": [
    "member entity ids"
  ],
  "member_names": [
    "member names"
  ]
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

===/api-reference/ontology===

# Ontology API

The entity and relationship type system for a namespace.

## Get namespace ontology

`GET /v1/default/namespaces/{namespace_id}/ontology`

The namespace's entity classes and typed relations, plus its resolved ontology_mode. Empty lists when no ontology is defined.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

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

Example response:

```json
{
  "classes": [
    {
      "id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "name": "Demo namespace"
    }
  ],
  "relations": [
    {
      "id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "name": "Demo namespace",
      "from_class": "from class",
      "to_class": "to class",
      "from_class_id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "to_class_id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "cardinality": "one-to-one"
    }
  ],
  "mode": "advisory"
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Replace namespace ontology

`PUT /v1/default/namespaces/{namespace_id}/ontology`

Whole-document replace. Classes/relations carrying a known id (from a prior GET) update in place, others match case-insensitively by name, leftovers insert, and items absent from the payload are deleted (entities of a deleted class degrade to unclassified). Rejects duplicate class names and relations whose endpoints do not name a class in the payload.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X PUT "https://api.illumina.sh/v1/default/namespaces/demo/ontology" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "classes": [],
  "relations": []
}'
```

Example response:

```json
{
  "classes": [
    {
      "id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "name": "Demo namespace"
    }
  ],
  "relations": [
    {
      "id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "name": "Demo namespace",
      "from_class": "from class",
      "to_class": "to class",
      "from_class_id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "to_class_id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "cardinality": "one-to-one"
    }
  ],
  "mode": "advisory"
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Classify unclassified entities

`POST /v1/default/namespaces/{namespace_id}/ontology/classify`

Backfill ontology classes onto unclassified entities from the CURRENT ontology (batched LLM calls; only NULL class assignments are filled). Asynchronous when a workflow engine is wired (202), synchronous otherwise. 400 when the namespace has no ontology classes.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/ontology/classify" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "status": "status",
  "async": false,
  "classified": 1
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Infer a draft ontology

`POST /v1/default/namespaces/{namespace_id}/ontology/infer`

Propose a draft ontology (classes + typed relations) from the namespace's extracted entities and co-occurrence graph via one LLM call. Asynchronous when a workflow engine is wired (202 + operation_id; poll the status endpoint), synchronous otherwise. The draft is stored for review — never auto-applied.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/ontology/infer" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "status": "status",
  "async": false,
  "draft": {
    "classes": [],
    "relations": []
  }
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get ontology inference status

`GET /v1/default/namespaces/{namespace_id}/ontology/infer/status`

Inference lifecycle (never/running/ready/failed) with the stored draft inline when ready.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/ontology/infer/status" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "status": "never"
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

===/api-reference/operations===

# Async operations API

Track, retry, and cancel asynchronous work started by retain and other endpoints.

## List async operations

`GET /v1/default/namespaces/{namespace_id}/operations`

Get a list of async operations for a specific agent, with optional filtering by status and operation type. Results are sorted by most recent first.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `status` | query | string | null | no | Filter by status: pending, processing, completed, failed, or cancelled |
| `type` | query | string | null | no | Filter by operation type: retain, consolidation, refresh_automation, file_convert_retain, webhook_delivery |
| `limit` | query | integer | no | Maximum number of operations to return |
| `offset` | query | integer | no | Number of operations to skip |
| `exclude_parents` | query | boolean | no | Exclude parent batch operations from results |

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

Example response:

```json
{
  "namespace_id": "user123",
  "limit": 20,
  "offset": 0,
  "operations": [
    {
      "created_at": "2024-01-15T10:30:00Z",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "pending",
      "task_type": "retain"
    }
  ],
  "total": 150
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get operation status

`GET /v1/default/namespaces/{namespace_id}/operations/{operation_id}`

Get the status of a specific async operation. Returns 'pending', 'completed', or 'failed'. Completed operations are removed from storage, so 'completed' means the operation finished successfully.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `operation_id` | path | string | yes |  |
| `include_payload` | query | boolean | no | Include the raw task payload (submission params) in the response. May be large. |

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

Example response:

```json
{
  "completed_at": "2024-01-15T10:31:30Z",
  "created_at": "2024-01-15T10:30:00Z",
  "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  "operation_type": "refresh_automations",
  "status": "completed",
  "updated_at": "2024-01-15T10:31:30Z"
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Cancel a pending async operation

`DELETE /v1/default/namespaces/{namespace_id}/operations/{operation_id}`

Cancel a pending async operation by removing it from the queue

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `operation_id` | path | string | yes |  |

```bash
curl -X DELETE "https://api.illumina.sh/v1/default/namespaces/demo/operations/ope_123" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "message": "Operation 550e8400-e29b-41d4-a716-446655440000 cancelled",
  "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  "success": true
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Retry a failed async operation

`POST /v1/default/namespaces/{namespace_id}/operations/{operation_id}/retry`

Re-queue a failed async operation so the worker picks it up again

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `operation_id` | path | string | yes |  |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/operations/ope_123/retry" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "message": "Operation 550e8400-e29b-41d4-a716-446655440000 queued for retry",
  "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  "success": true
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

===/api-reference/compilation===

# Compilation API

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

## List promotion decisions

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

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `outcome` | query | "promoted" | "rejected" | no |  |
| `trigger_id` | query | string (uuid) | null | no |  |
| `source_namespace_id` | query | string | null | no |  |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |

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

Example response:

```json
{
  "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
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Run a compilation sweep

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

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
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
}'
```

Example response:

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

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## List compilation triggers

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

List the escalation triggers governing what this compilation namespace promotes.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

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

Example response:

```json
{
  "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
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Create a compilation trigger

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

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
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"
}'
```

Example response:

```json
{
  "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"
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Update a compilation trigger

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

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `trigger_id` | path | string (uuid) | yes |  |

```bash
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"
}'
```

Example response:

```json
{
  "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"
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Delete a compilation trigger

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

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `trigger_id` | path | string (uuid) | yes |  |

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

Example response:

```json
{
  "deleted": false
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

===/api-reference/webhooks===

# Webhooks API

HMAC-signed event delivery to your endpoints when namespace activity occurs.

## Register webhook

`POST /v1/default/namespaces/{namespace_id}/webhooks`

Register a webhook endpoint to receive event notifications for this namespace.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/webhooks" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/illumina"
}'
```

Example response:

```json
{
  "id": "ite_123",
  "namespace_id": "demo",
  "url": "https://example.com/webhooks/illumina",
  "event_types": [
    "event types"
  ],
  "enabled": false
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## List webhooks

`GET /v1/default/namespaces/{namespace_id}/webhooks`

List all webhooks registered for a namespace.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

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

Example response:

```json
{
  "items": [
    {
      "id": "ite_123",
      "namespace_id": "demo",
      "url": "https://example.com/webhooks/illumina",
      "event_types": [
        "event types"
      ],
      "enabled": false
    }
  ]
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Delete webhook

`DELETE /v1/default/namespaces/{namespace_id}/webhooks/{webhook_id}`

Remove a registered webhook.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `webhook_id` | path | string | yes |  |

```bash
curl -X DELETE "https://api.illumina.sh/v1/default/namespaces/demo/webhooks/web_123" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "deleted_count": 10,
  "message": "Deleted successfully",
  "success": true
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Update webhook

`PATCH /v1/default/namespaces/{namespace_id}/webhooks/{webhook_id}`

Update one or more fields of a registered webhook. Only provided fields are changed.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `webhook_id` | path | string | yes |  |

```bash
curl -X PATCH "https://api.illumina.sh/v1/default/namespaces/demo/webhooks/web_123" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/illumina",
  "secret": "secret",
  "event_types": [
    "event types"
  ],
  "enabled": false
}'
```

Example response:

```json
{
  "id": "ite_123",
  "namespace_id": "demo",
  "url": "https://example.com/webhooks/illumina",
  "event_types": [
    "event types"
  ],
  "enabled": false
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## List webhook deliveries

`GET /v1/default/namespaces/{namespace_id}/webhooks/{webhook_id}/deliveries`

Inspect delivery history for a webhook (useful for debugging).

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `webhook_id` | path | string | yes |  |
| `limit` | query | integer | no | Maximum number of deliveries to return |
| `cursor` | query | string | null | no | Pagination cursor (created_at of last item) |

```bash
curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/webhooks/web_123/deliveries" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "items": [
    {
      "id": "ite_123",
      "webhook_id": "web_123",
      "url": "https://example.com/webhooks/illumina",
      "event_type": "event type",
      "status": "status",
      "attempts": 1
    }
  ]
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

===/api-reference/audit===

# Audit logs API

Query the audit trail of recall and MCP activity in a namespace.

## List audit logs

`GET /v1/default/namespaces/{namespace_id}/audit-logs`

List audit log entries for a namespace, ordered by most recent first.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `action` | query | string | null | no | Filter by action type |
| `transport` | query | string | null | no | Filter by transport (http, mcp, system) |
| `start_date` | query | string | null | no | Filter from this ISO datetime (inclusive) |
| `end_date` | query | string | null | no | Filter until this ISO datetime (exclusive) |
| `limit` | query | integer | no | Max items to return |
| `offset` | query | integer | no | Offset for pagination |

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

Example response:

```json
{
  "namespace_id": "demo",
  "total": 1,
  "limit": 1,
  "offset": 1,
  "items": [
    {
      "id": "ite_123",
      "action": "action",
      "transport": "transport",
      "namespace_id": "demo",
      "started_at": "started at",
      "ended_at": "ended at",
      "request": {},
      "response": {},
      "metadata": {}
    }
  ]
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Audit log statistics

`GET /v1/default/namespaces/{namespace_id}/audit-logs/stats`

Get audit log counts grouped by time bucket for charting.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `action` | query | string | null | no | Filter by action type |
| `period` | query | string | no | Time period: 1d, 7d, or 30d |

```bash
curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/audit-logs/stats" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "namespace_id": "demo",
  "period": "period",
  "trunc": "trunc",
  "start": "start",
  "buckets": [
    {
      "time": "time",
      "actions": {
        "key": 1
      },
      "total": 1
    }
  ]
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

===/api-reference/namespace-templates===

# Namespace templates API

Export a namespace's configuration as a template and import it elsewhere.

## Export namespace template

`GET /v1/default/namespaces/{namespace_id}/export`

Export a namespace's current configuration, automations, and directives as a template manifest. The exported manifest can be imported into another namespace to replicate the setup.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |

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

Example response:

```json
{
  "namespace": {
    "disposition_empathy": 5,
    "enable_observations": true,
    "reflect_mission": "You are helping a support agent remember customer interactions.",
    "retain_mission": "Extract customer issues, resolutions, and sentiment."
  },
  "directives": [
    {
      "content": "Always respond with empathy and understanding.",
      "name": "Always be empathetic",
      "priority": 10
    }
  ],
  "automations": [
    {
      "id": "sentiment-overview",
      "name": "Customer Sentiment Overview",
      "source_query": "What is the overall sentiment trend?",
      "trigger": {
        "refresh_after_consolidation": true
      }
    }
  ],
  "version": "1"
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Import namespace template

`POST /v1/default/namespaces/{namespace_id}/import`

Import a namespace template manifest to create or update a namespace's configuration, automations, and directives. If the namespace does not exist it is created. Config fields are applied as per-namespace overrides. Automations are matched by id, directives by name — existing ones are updated, new ones are created. Use dry_run=true to validate the manifest without applying changes.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace_id` | path | string | yes |  |
| `dry_run` | query | boolean | no | Validate only, do not apply changes |

```bash
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/import" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "namespace_id": "demo",
  "config_applied": false
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410, 422

## Get namespace template JSON Schema

`GET /v1/namespace-template-schema`

Returns the JSON Schema for the namespace template manifest format. Use this to validate template manifests before importing.

```bash
curl -X GET "https://api.illumina.sh/v1/namespace-template-schema" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
null
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410

===/api-reference/monitoring===

# Monitoring API

Service health and version endpoints.

## Health check endpoint

`GET /health`

Checks the health of the API and database connection

```bash
curl -X GET "https://api.illumina.sh/health" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
null
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410

## Get API version and feature flags

`GET /version`

Returns API version information and enabled feature flags. Use this to check which capabilities are available in this deployment.

```bash
curl -X GET "https://api.illumina.sh/version" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
```

Example response:

```json
{
  "api_version": "0.4.0",
  "features": {
    "namespace_config_api": false,
    "file_upload_api": true,
    "mcp": true,
    "observations": false,
    "worker": true
  }
}
```

Error statuses: 400, 401, 402, 403, 404, 405, 409, 410