API reference · 15 endpoints

Namespaces

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

GETList all memory namespaces/v1/default/namespaces
PUTCreate or update memory namespace/v1/default/namespaces/{namespace_id}
PATCHPartial update memory namespace/v1/default/namespaces/{namespace_id}
DELETEDelete memory namespace/v1/default/namespaces/{namespace_id}
POSTAdd/merge memory namespace background (deprecated)/v1/default/namespaces/{namespace_id}/background
GETGet namespace configuration/v1/default/namespaces/{namespace_id}/config
PATCHUpdate namespace configuration/v1/default/namespaces/{namespace_id}/config
DELETEReset namespace configuration/v1/default/namespaces/{namespace_id}/config
POSTTrigger consolidation/v1/default/namespaces/{namespace_id}/consolidate
POSTRecover failed consolidation/v1/default/namespaces/{namespace_id}/consolidation/recover
DELETEClear all observations/v1/default/namespaces/{namespace_id}/observations
GETGet memory namespace profile/v1/default/namespaces/{namespace_id}/profile
PUTUpdate memory namespace disposition/v1/default/namespaces/{namespace_id}/profile
GETGet statistics for memory namespace/v1/default/namespaces/{namespace_id}/stats
GETMemory ingestion time-series/v1/default/namespaces/{namespace_id}/stats/memories-timeseries

GET/v1/default/namespaces

List all memory namespaces

Get a list of all agents with their profiles

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

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

Response · 200

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

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

PUT/v1/default/namespaces/{namespace_id}

Create or update memory namespace

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

Parameters

namespace_idstringpathrequired

Request body · application/json

namestring | null

Deprecated: display label only, not advertised

dispositionDispositionTraits

Deprecated: use update_namespace_config instead

skepticismintegerrequired

How skeptical vs trusting (1=trusting, 5=skeptical)

literalismintegerrequired

How literally to interpret information (1=flexible, 5=literal)

empathyintegerrequired

How much to consider emotional context (1=detached, 5=empathetic)

disposition_skepticisminteger | null

Deprecated: use update_namespace_config instead

disposition_literalisminteger | null

Deprecated: use update_namespace_config instead

disposition_empathyinteger | null

Deprecated: use update_namespace_config instead

missionstring | null

Deprecated: use update_namespace_config with reflect_mission instead

backgroundstring | null

Deprecated: use update_namespace_config with reflect_mission instead

reflect_missionstring | null

Mission/context for Reflect operations. Guides how Reflect interprets and uses memories.

retain_missionstring | null

Steers what gets extracted during retain(). Injected alongside built-in extraction rules.

retain_extraction_modestring | null

Fact extraction mode: 'concise' (default), 'verbose', or 'custom'.

retain_custom_instructionsstring | null

Custom extraction prompt. Only active when retain_extraction_mode is 'custom'.

retain_chunk_sizeinteger | null

Maximum token size for each content chunk during retain.

enable_observationsboolean | null

Toggle automatic observation consolidation after retain().

observations_missionstring | null

Controls what gets synthesised into observations. Replaces built-in consolidation rules entirely.

kind"standard" | "compilation"

standard, or compilation to promote memories in from other namespaces

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

Response · 200

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

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

PATCH/v1/default/namespaces/{namespace_id}

Partial update memory namespace

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

Parameters

namespace_idstringpathrequired

Request body · application/json

namestring | null

Deprecated: display label only, not advertised

dispositionDispositionTraits

Deprecated: use update_namespace_config instead

skepticismintegerrequired

How skeptical vs trusting (1=trusting, 5=skeptical)

literalismintegerrequired

How literally to interpret information (1=flexible, 5=literal)

empathyintegerrequired

How much to consider emotional context (1=detached, 5=empathetic)

disposition_skepticisminteger | null

Deprecated: use update_namespace_config instead

disposition_literalisminteger | null

Deprecated: use update_namespace_config instead

disposition_empathyinteger | null

Deprecated: use update_namespace_config instead

missionstring | null

Deprecated: use update_namespace_config with reflect_mission instead

backgroundstring | null

Deprecated: use update_namespace_config with reflect_mission instead

reflect_missionstring | null

Mission/context for Reflect operations. Guides how Reflect interprets and uses memories.

retain_missionstring | null

Steers what gets extracted during retain(). Injected alongside built-in extraction rules.

retain_extraction_modestring | null

Fact extraction mode: 'concise' (default), 'verbose', or 'custom'.

retain_custom_instructionsstring | null

Custom extraction prompt. Only active when retain_extraction_mode is 'custom'.

retain_chunk_sizeinteger | null

Maximum token size for each content chunk during retain.

enable_observationsboolean | null

Toggle automatic observation consolidation after retain().

observations_missionstring | null

Controls what gets synthesised into observations. Replaces built-in consolidation rules entirely.

kind"standard" | "compilation"

standard, or compilation to promote memories in from other namespaces

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

import httpx

response = httpx.patch(
    "https://api.illumina.sh/v1/default/namespaces/demo",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "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."
    },
)
print(response.json())

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "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."
  }),
});
console.log(await response.json());

Response · 200

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

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

DELETE/v1/default/namespaces/{namespace_id}

Delete memory namespace

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

Parameters

namespace_idstringpathrequired

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

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

Response · 200

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

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

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

Add/merge memory namespace background (deprecated)

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

Parameters

namespace_idstringpathrequired

Request body · application/json

contentstringrequired

New background information to add or merge

update_dispositionbooleandefault true

Deprecated - disposition is no longer auto-inferred from mission

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

import httpx

response = httpx.post(
    "https://api.illumina.sh/v1/default/namespaces/demo/background",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "content": "I was born in Texas",
        "update_disposition": True
    },
)
print(response.json())

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/background", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "content": "I was born in Texas",
    "update_disposition": true
  }),
});
console.log(await response.json());

Response · 200

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

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

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.

Parameters

namespace_idstringpathrequired

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

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

Response · 200

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

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

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

Update namespace configuration

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

Parameters

namespace_idstringpathrequired

Request body · application/json

updatesobjectrequired

Configuration overrides. Keys can be in Python field format (llm_provider) or environment variable format (ILLUMINA_API_LLM_PROVIDER). Only hierarchical fields can be overridden per-namespace.

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

import httpx

response = httpx.patch(
    "https://api.illumina.sh/v1/default/namespaces/demo/config",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "updates": {
            "llm_model": "claude-sonnet-4-5",
            "retain_custom_instructions": "Extract technical details carefully",
            "retain_extraction_mode": "verbose"
        }
    },
)
print(response.json())

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/config", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "updates": {
      "llm_model": "claude-sonnet-4-5",
      "retain_custom_instructions": "Extract technical details carefully",
      "retain_extraction_mode": "verbose"
    }
  }),
});
console.log(await response.json());

Response · 200

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

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

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

Reset namespace configuration

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

Parameters

namespace_idstringpathrequired

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

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

Response · 200

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

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

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

Trigger consolidation

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

Parameters

namespace_idstringpathrequired

Request body · application/json

observation_scopesstring[][]

Optional list of tag scopes to consolidate. Each scope is a list of tags. Only unconsolidated memories whose tags contain all tags in at least one scope will be processed. If omitted, all unconsolidated memories are processed.

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

import httpx

response = httpx.post(
    "https://api.illumina.sh/v1/default/namespaces/demo/consolidate",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "observation_scopes": [
            [
                "observation scopes"
            ]
        ]
    },
)
print(response.json())

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

Response · 200

{
  "operation_id": "ope_123"
}

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

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

Recover failed consolidation

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.

Parameters

namespace_idstringpathrequired

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

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

Response · 200

{
  "retried_count": 42
}

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

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

Clear all observations

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

Parameters

namespace_idstringpathrequired

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

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

Response · 200

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

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

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

Get memory namespace profile

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

Parameters

namespace_idstringpathrequired

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

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

Response · 200

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

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

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

Update memory namespace disposition

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

Parameters

namespace_idstringpathrequired

Request body · application/json

dispositionDispositionTraitsrequired

Disposition traits that influence how memories are formed and interpreted.

skepticismintegerrequired

How skeptical vs trusting (1=trusting, 5=skeptical)

literalismintegerrequired

How literally to interpret information (1=flexible, 5=literal)

empathyintegerrequired

How much to consider emotional context (1=detached, 5=empathetic)

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

import httpx

response = httpx.put(
    "https://api.illumina.sh/v1/default/namespaces/demo/profile",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "disposition": {
            "empathy": 3,
            "literalism": 3,
            "skepticism": 3
        }
    },
)
print(response.json())

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/profile", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "disposition": {
      "empathy": 3,
      "literalism": 3,
      "skepticism": 3
    }
  }),
});
console.log(await response.json());

Response · 200

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

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

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

Get statistics for memory namespace

Get statistics about nodes and links for a specific agent

Parameters

namespace_idstringpathrequired

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

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

Response · 200

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

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

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

Memory ingestion time-series

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

Parameters

namespace_idstringpathrequired

periodstringquery

time_fieldstringquery

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

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

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

Response · 200

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

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

Getting started

Core concepts

SDKs & tools

API reference

Resources

Parameters

Request body · application/json

Parameters

Request body · application/json

Parameters

Parameters

Request body · application/json

Parameters

Parameters

Request body · application/json

Parameters

Parameters

Request body · application/json

Parameters

Parameters

Parameters

Parameters

Request body · application/json

Parameters

Parameters

Search docs