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. 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.
  • Budgets: recall and reflect take budget (low, mid, high) to trade latency for retrieval depth.
  • Errors share one envelope and status vocabulary — see Errors. Rate limits are described in Rate limits.

Sections

Memory

Retain, recall, reflect, decisions, tags, graph.

Namespaces

Lifecycle, config, consolidation, stats.

Documents

Documents behind memories, chunks, reprocessing.

Files

File upload for OCR and retention.

Automations

Standing reflect queries that stay current.

Directives

Standing instructions steering retain and recall.

Entities

Extracted entities and the entity graph.

Communities

Clusters of related memories.

Ontology

Entity and relationship type system.

Async operations

Operation status, retry, cancel.

Compilation

Promotion triggers and sweeps.

Webhooks

Signed event delivery.

Audit logs

Recall and MCP activity trail.

Namespace templates

Export and import namespace configuration.

Monitoring

Health and version.

Search docs

Search the documentation