API reference · 5 endpoints

Directives

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

GETList directives/v1/default/namespaces/{namespace_id}/directives
POSTCreate directive/v1/default/namespaces/{namespace_id}/directives
GETGet directive/v1/default/namespaces/{namespace_id}/directives/{directive_id}
PATCHUpdate directive/v1/default/namespaces/{namespace_id}/directives/{directive_id}
DELETEDelete directive/v1/default/namespaces/{namespace_id}/directives/{directive_id}

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

List directives

List hard rules that are injected into prompts.

Parameters

namespace_idstringpathrequired

tagsstring[]query

Filter by tags

tags_match"any" | "all" | "exact"query

How to match tags

active_onlybooleanquery

Only return active directives

limitintegerquery

offsetintegerquery

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

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

Response · 200

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

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

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

Create directive

Create a hard rule that will be injected into prompts.

Parameters

namespace_idstringpathrequired

Request body · application/json

namestringrequired

Human-readable name for the directive

contentstringrequired

The directive text to inject into prompts

priorityintegerdefault 0

Higher priority directives are injected first

is_activebooleandefault true

Whether this directive is active

tagsstring[]default []

Tags for filtering

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

import httpx

response = httpx.post(
    "https://api.illumina.sh/v1/default/namespaces/demo/directives",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "name": "Demo namespace",
        "content": "Ada shipped the payments rewrite in Q3 2025."
    },
)
print(response.json())

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/directives", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Demo namespace",
    "content": "Ada shipped the payments rewrite in Q3 2025."
  }),
});
console.log(await response.json());

Response · 200

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

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

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

Get directive

Get a specific directive by ID.

Parameters

namespace_idstringpathrequired

directive_idstringpathrequired

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

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

Response · 200

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

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

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

Update directive

Update a directive's properties.

Parameters

namespace_idstringpathrequired

directive_idstringpathrequired

Request body · application/json

namestring | null

New name

contentstring | null

New content

priorityinteger | null

New priority

is_activeboolean | null

New active status

tagsstring[]

New tags

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

import httpx

response = httpx.patch(
    "https://api.illumina.sh/v1/default/namespaces/demo/directives/dir_123",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "name": "Demo namespace",
        "content": "Ada shipped the payments rewrite in Q3 2025.",
        "priority": 1,
        "is_active": False
    },
)
print(response.json())

const response = await fetch("https://api.illumina.sh/v1/default/namespaces/demo/directives/dir_123", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.ILLUMINA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Demo namespace",
    "content": "Ada shipped the payments rewrite in Q3 2025.",
    "priority": 1,
    "is_active": false
  }),
});
console.log(await response.json());

Response · 200

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

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

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

Delete directive

Delete a directive.

Parameters

namespace_idstringpathrequired

directive_idstringpathrequired

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

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

Response · 200

null

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

Getting started

Core concepts

SDKs & tools

API reference

Resources

Directives

List directives

Parameters

Create directive

Parameters

Request body · application/json

Get directive

Parameters

Update directive

Parameters

Request body · application/json

Delete directive

Parameters

Getting started

Core concepts

SDKs & tools

API reference

Resources

List directives

Parameters

Create directive

Parameters

Request body · application/json

Get directive

Parameters

Update directive

Parameters

Request body · application/json

Delete directive

Parameters

Search docs