API reference · 5 endpoints

Ontology

The entity and relationship type system for a namespace.

GETGet namespace ontology/v1/default/namespaces/{namespace_id}/ontology
PUTReplace namespace ontology/v1/default/namespaces/{namespace_id}/ontology
POSTClassify unclassified entities/v1/default/namespaces/{namespace_id}/ontology/classify
POSTInfer a draft ontology/v1/default/namespaces/{namespace_id}/ontology/infer
GETGet ontology inference status/v1/default/namespaces/{namespace_id}/ontology/infer/status

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

Get namespace ontology

The namespace's entity classes and typed relations, plus its resolved ontology_mode. Empty lists when no ontology is defined.

Parameters

namespace_idstringpathrequired

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

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

Response · 200

{
  "classes": [
    {
      "id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "name": "Demo namespace"
    }
  ],
  "relations": [
    {
      "id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "name": "Demo namespace",
      "from_class": "from class",
      "to_class": "to class",
      "from_class_id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "to_class_id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "cardinality": "one-to-one"
    }
  ],
  "mode": "advisory"
}

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

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

Whole-document replace. Classes/relations carrying a known id (from a prior GET) update in place, others match case-insensitively by name, leftovers insert, and items absent from the payload are deleted (entities of a deleted class degrade to unclassified). Rejects duplicate class names and relations whose endpoints do not name a class in the payload.

Parameters

namespace_idstringpathrequired

Request body · application/json

classesOntologyClassInput[]default []

idstring (uuid) | null

namestringrequired

descriptionstringdefault ""

propertiesOntologyClassProperty[]default []

namestringrequired

descriptionstring | null

iconstring | null

colorstring | null

relationsOntologyRelationInput[]default []

idstring (uuid) | null

namestringrequired

from_classstringrequired

to_classstringrequired

cardinality"one-to-one" | "one-to-many" | "many-to-one" | "many-to-many"default "many-to-many"

descriptionstringdefault ""

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

import httpx

response = httpx.put(
    "https://api.illumina.sh/v1/default/namespaces/demo/ontology",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "classes": [],
        "relations": []
    },
)
print(response.json())

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

Response · 200

{
  "classes": [
    {
      "id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "name": "Demo namespace"
    }
  ],
  "relations": [
    {
      "id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "name": "Demo namespace",
      "from_class": "from class",
      "to_class": "to class",
      "from_class_id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "to_class_id": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b",
      "cardinality": "one-to-one"
    }
  ],
  "mode": "advisory"
}

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

POST/v1/default/namespaces/{namespace_id}/ontology/classify

Classify unclassified entities

Backfill ontology classes onto unclassified entities from the CURRENT ontology (batched LLM calls; only NULL class assignments are filled). Asynchronous when a workflow engine is wired (202), synchronous otherwise. 400 when the namespace has no ontology classes.

Parameters

namespace_idstringpathrequired

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

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

Response · 200

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

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

POST/v1/default/namespaces/{namespace_id}/ontology/infer

Infer a draft ontology

Propose a draft ontology (classes + typed relations) from the namespace's extracted entities and co-occurrence graph via one LLM call. Asynchronous when a workflow engine is wired (202 + operation_id; poll the status endpoint), synchronous otherwise. The draft is stored for review — never auto-applied.

Parameters

namespace_idstringpathrequired

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

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

Response · 200

{
  "status": "status",
  "async": false,
  "draft": {
    "classes": [],
    "relations": []
  }
}

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

GET/v1/default/namespaces/{namespace_id}/ontology/infer/status

Get ontology inference status

Inference lifecycle (never/running/ready/failed) with the stored draft inline when ready.

Parameters

namespace_idstringpathrequired

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

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

Response · 200

{
  "status": "never"
}

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

Getting started

Core concepts

SDKs & tools

API reference

Resources

Ontology

Get namespace ontology

Parameters

Replace namespace ontology

Parameters

Request body · application/json

Classify unclassified entities

Parameters

Infer a draft ontology

Parameters

Get ontology inference status

Parameters

Getting started

Core concepts

SDKs & tools

API reference

Resources

Get namespace ontology

Parameters

Replace namespace ontology

Parameters

Request body · application/json

Classify unclassified entities

Parameters

Infer a draft ontology

Parameters

Get ontology inference status

Parameters

Search docs