API reference · 7 endpoints

Documents

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

GETGet chunk details/v1/default/chunks/{chunk_id}
GETList documents/v1/default/namespaces/{namespace_id}/documents
GETGet document details/v1/default/namespaces/{namespace_id}/documents/{document_id}
PATCHUpdate document/v1/default/namespaces/{namespace_id}/documents/{document_id}
DELETEDelete a document/v1/default/namespaces/{namespace_id}/documents/{document_id}
GETList document chunks/v1/default/namespaces/{namespace_id}/documents/{document_id}/chunks
POSTReprocess document/v1/default/namespaces/{namespace_id}/documents/{document_id}/reprocess

GET/v1/default/chunks/{chunk_id}

Get chunk details

Get a specific chunk by its ID

Parameters

chunk_idstringpathrequired

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

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

Response · 200

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

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

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

List documents

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

Parameters

namespace_idstringpathrequired

qstring | nullquery

Case-insensitive substring filter on document ID (e.g. 'report' matches 'report-2024')

tagsstring[]query

Filter documents by tags

tags_matchstringquery

How to match tags: 'any', 'all', 'any_strict', 'all_strict'

limitintegerquery

offsetintegerquery

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

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

Response · 200

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

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

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

Get document details

Get a specific document including its original text

Parameters

namespace_idstringpathrequired

document_idstringpathrequired

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

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

Response · 200

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

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

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

Update document

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.

Parameters

namespace_idstringpathrequired

document_idstringpathrequired

Request body · application/json

tagsstring[]

New tags for the document and its memory units. Triggers observation invalidation and re-consolidation.

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"
  ]
}'

import httpx

response = httpx.patch(
    "https://api.illumina.sh/v1/default/namespaces/demo/documents/doc_123",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "tags": [
            "team-a",
            "team-b"
        ]
    },
)
print(response.json())

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/documents/doc_123", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "tags": [
      "team-a",
      "team-b"
    ]
  }),
});
console.log(await response.json());

Response · 200

{
  "success": true
}

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

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

Delete a document

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.

Parameters

namespace_idstringpathrequired

document_idstringpathrequired

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

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

Response · 200

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

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

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

List document chunks

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

Parameters

namespace_idstringpathrequired

document_idstringpathrequired

limitintegerquery

Maximum number of chunks to return

offsetintegerquery

Offset for pagination

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

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

Response · 200

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

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

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

Reprocess document

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.

Parameters

namespace_idstringpathrequired

document_idstringpathrequired

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

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

Response · 200

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

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

Getting started

Core concepts

SDKs & tools

API reference

Resources

Documents

Get chunk details

Parameters

List documents

Parameters

Get document details

Parameters

Update document

Parameters

Request body · application/json

Delete a document

Parameters

List document chunks

Parameters

Reprocess document

Parameters

Getting started

Core concepts

SDKs & tools

API reference

Resources

Get chunk details

Parameters

List documents

Parameters

Get document details

Parameters

Update document

Parameters

Request body · application/json

Delete a document

Parameters

List document chunks

Parameters

Reprocess document

Parameters

Search docs