API reference · 5 endpoints

Communities

Clusters of related memories detected across the namespace graph.

GETList communities/v1/default/namespaces/{namespace_id}/communities
DELETEClear communities/v1/default/namespaces/{namespace_id}/communities
POSTBuild communities/v1/default/namespaces/{namespace_id}/communities/build
GETGet community build status/v1/default/namespaces/{namespace_id}/communities/status
GETGet community/v1/default/namespaces/{namespace_id}/communities/{community_id}

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

List communities

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

Parameters

namespace_idstringpathrequired

limitintegerquery

Maximum number of communities to return

offsetintegerquery

Offset for pagination

qstring | nullquery

Case-insensitive title/summary search

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

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

Response · 200

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

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

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

Clear communities

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

Parameters

namespace_idstringpathrequired

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

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

Response · 200

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

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

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

Build communities

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

Parameters

namespace_idstringpathrequired

Request body · application/json

asyncbooleandefault true

Start a background build workflow (default) or build synchronously.

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

import httpx

response = httpx.post(
    "https://api.illumina.sh/v1/default/namespaces/demo/communities/build",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "async": True
    },
)
print(response.json())

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

Response · 200

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

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

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

Get community build status

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

Parameters

namespace_idstringpathrequired

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

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

Response · 200

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

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

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

Get community

Fetch one community by id, including its member entities.

Parameters

namespace_idstringpathrequired

community_idstringpathrequired

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

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

Response · 200

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

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

Getting started

Core concepts

SDKs & tools

API reference

Resources

Communities

List communities

Parameters

Clear communities

Parameters

Build communities

Parameters

Request body · application/json

Get community build status

Parameters

Get community

Parameters

Getting started

Core concepts

SDKs & tools

API reference

Resources

List communities

Parameters

Clear communities

Parameters

Build communities

Parameters

Request body · application/json

Get community build status

Parameters

Get community

Parameters

Search docs