---
title: "Return the top entities extracted from a single document."
method: GET
path: "/v1/documents/{document_id}/entities"
tags: ["documents"]
---

# Return the top entities extracted from a single document.

`GET /v1/documents/{document_id}/entities`

## Request

- Base URL: `https://api.andish.ru` (the document declares no server; this is the origin it was published from)
- URL: `https://api.andish.ru/v1/documents/{document_id}/entities`
- Auth: none declared

Returns a flat list of this document's entities (name, type, degree), ordered by connectivity DESC — the same ranking ``GET /v1/graph`` uses for its top-N view.

**Why this endpoint exists:** ``GET /v1/graph`` returns workspace-wide entities with no per-document link; using it to build per-document prompts leaked entities from other documents. This endpoint resolves the document -> chunks -> entities -> graph-node chain server-side.

**Isolation:** 404 is returned uniformly for a missing OR cross-tenant ``document_id`` (no existence leak).

**Ceiling:** ``limit`` is capped server-side; values above the ceiling are rejected (422), never silently clamped.

## Path parameters

- `document_id` string, uuid, required: Document UUID.

## Query parameters

- `limit` integer: Maximum number of entities to return. Default 10, server ceiling 50.

## Response `200`

Successful Response

- DocumentEntitiesResponse: 200 response for GET /v1/documents/{document_id}/entities.
  - `items` DocumentEntityRef[], required: Top entities of this document, ordered by degree DESC, name ASC.
    - `name` string, required: Entity node_id / label.
    - `type` string, required: Canonical entity type (GRAPH_NODE_TYPES taxonomy).
    - `degree` integer, required: Workspace-wide connectivity (incident edge count).
  - `total` integer, required: Total distinct entities linked to this document.
  - `truncated` boolean, required: True when ``total`` exceeds the number of returned ``items``.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/andish/apis/mnemo-api.md) · [All operations](https://skmtc.dev/andish/apis/mnemo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/andish/apis/mnemo-api/revisions/d5449f23414c?raw)