For the complete BrainAPI documentation index, see llms.txt. A markdown version of any docs page is available by appending .md to its URL. Docs MCP: /docs/mcp.
Existence API — Check an entity
Check whether a named entity exists and inspect its relationships and observations
Use GET /retrieve/entity/status when your application has a named thing and needs to resolve it to a graph node. This is a graph lookup, not a ranked document search.
What this answers
The endpoint answers four related questions:
- Did BrainAPI resolve the target to a node?
- Does that node have graph relationships?
- Which relationship-and-neighbor pairs are attached to it?
- Which observations are stored for that node?
For example, an incident tool can check whether payments-api is already represented before creating a duplicate service node. A learning application can check for a course by name before attaching a preference.
Before you call it
Ingest or create the entity first. The selected brain must contain graph nodes and node embeddings; passage-only ingestion with skip_enrichment=true does not create them.
Send a BrainPAT and an explicit brain scope:
curl --get "http://localhost:8000/retrieve/entity/status" \
-H "BrainPAT: $BRAINPAT_TOKEN" \
-H "X-Brain-ID: operations" \
--data-urlencode "target=payments-api" \
--data-urlencode "types=SERVICE"Repeat types to allow more than one label:
?target=payments-api&types=SERVICE&types=APPLICATIONRead the response
When a node resolves, the response has this shape:
{
"node": {
"uuid": "service-42",
"labels": ["SERVICE"],
"name": "payments-api"
},
"exists": true,
"has_relationships": true,
"relationships": [],
"observations": []
}relationships contains predicate-and-neighbor pairs when present. observations contains stored observation objects, not generated prose.
No match is a successful lookup with an empty result, not an HTTP error:
{
"node": null,
"exists": false,
"has_relationships": false,
"relationships": [],
"observations": []
}Exact request contract
| Parameter | Required | Meaning |
|---|---|---|
target | Yes | Text used to resolve a graph node through node-vector similarity. |
types | No | Repeated label filter. BrainAPI selects the first resolved candidate whose labels intersect this list. |
X-Brain-ID | Recommended | Brain scope. See Authentication and brains. |
Because resolution is similarity-based, exists=true means BrainAPI found the best eligible node; it does not prove an exact identifier match. If exact identity matters, store and retrieve stable UUIDs through the Model API.
When to use another surface
| Need | Better surface |
|---|---|
| Find passages that mention a service | Search |
| Assemble evidence for a model prompt | Context |
| List entities by label or text | GET /retrieve/entities in the Retrieve reference |
| Inspect a known UUID's neighbors | GET /retrieve/entities/neighbors in the Retrieve reference |
| Find peer entities connected through shared anchors | Find related entities |
Troubleshoot
| Symptom | Likely cause | What to check |
|---|---|---|
exists=false after ingestion | The asynchronous task has not completed, the brain differs, or the entity was not extracted. | Poll the task, compare X-Brain-ID, and list entities in the selected brain. |
| An unexpected node resolves | The target is ambiguous or the eligible label set is too broad. | Add types, use a more specific target, or resolve by UUID through Model operations. |
exists=true but no relationships | The node is isolated or only passage data was saved. | Inspect structured ingestion and graph creation. |
Next, learn how to find related entities or choose a different retrieval surface.
Last updated on