# Existence API — Check an entity (https://brainapi.lumen-labs.ai/docs/v2/retrieval/entities/existence)

> For the complete BrainAPI documentation index, see [llms.txt](https://brainapi.lumen-labs.ai/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL (e.g. https://brainapi.lumen-labs.ai/docs/v2/retrieval/entities/existence.md).

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:

```bash
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:

```text
?target=payments-api&types=SERVICE&types=APPLICATION
```

## Read the response

When a node resolves, the response has this shape:

```json
{
  "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:

```json
{
  "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](https://brainapi.lumen-labs.ai/docs/v2/brains-and-auth). |

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](https://brainapi.lumen-labs.ai/docs/v2/model).

## When to use another surface

| Need | Better surface |
| --- | --- |
| Find passages that mention a service | [Search](https://brainapi.lumen-labs.ai/docs/v2/retrieval/search) |
| Assemble evidence for a model prompt | [Context](https://brainapi.lumen-labs.ai/docs/v2/retrieval/context) |
| List entities by label or text | `GET /retrieve/entities` in the [Retrieve reference](https://brainapi.lumen-labs.ai/docs/v2/reference/api/retrieve) |
| Inspect a known UUID's neighbors | `GET /retrieve/entities/neighbors` in the [Retrieve reference](https://brainapi.lumen-labs.ai/docs/v2/reference/api/retrieve) |
| Find peer entities connected through shared anchors | [Find related entities](https://brainapi.lumen-labs.ai/docs/v2/retrieval/entities/synergies) |

## 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](https://brainapi.lumen-labs.ai/docs/v2/retrieval/entities/synergies) or choose a different [retrieval surface](https://brainapi.lumen-labs.ai/docs/v2/retrieval).