Get Document Chunks

Get all chunks for a specific document. Chunks are the atomic text segments created during ingestion, each with its own embedding for semantic search.

GET /api/v1/chunks/:document_id

Authentication

Requires an API key with the read permission.

Header	Value
X-API-Key	ink_live_abc123...

Path Parameters

Parameter	Type	Required	Description
document_id	string	Yes	The unique identifier (UUID) of the document whose chunks to retrieve

Code Examples

cURL

curl https://api.inherent.systems/api/v1/chunks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: $INHERENT_API_KEY"

Python

import requests

document_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

response = requests.get(
    f"https://api.inherent.systems/api/v1/chunks/{document_id}",
    headers={"X-API-Key": "ink_live_abc123..."},
)

chunks = response.json()
for chunk in chunks:
    print(f"Chunk {chunk['chunk_index']}: {chunk['token_count']} tokens")
    print(f"  {chunk['content'][:80]}...")

JavaScript

const documentId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";

const response = await fetch(
  `https://api.inherent.systems/api/v1/chunks/${documentId}`,
  {
    headers: {
      "X-API-Key": "ink_live_abc123...",
    },
  }
);

const chunks = await response.json();
chunks.forEach((chunk) => {
  console.log(`Chunk ${chunk.chunk_index}: ${chunk.token_count} tokens`);
});

Response

Status: 200 OK

The response is a JSON array of chunk objects, ordered by chunk_index.

[
  {
    "id": "c1d2e3f4-0001-4000-8000-000000000001",
    "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "content": "# API Authentication\n\nAll API requests require authentication using a Bearer token or X-API-Key header. Include your API key in the request header to access any protected endpoint.",
    "chunk_index": 0,
    "token_count": 128,
    "metadata": {
      "heading": "API Authentication"
    }
  },
  {
    "id": "c1d2e3f4-0001-4000-8000-000000000002",
    "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "content": "## Creating an API Key\n\nTo create an API key, navigate to Settings > API Keys in the dashboard. Each key can be scoped with specific permissions: read, write, and search.",
    "chunk_index": 1,
    "token_count": 135,
    "metadata": {
      "heading": "Creating an API Key"
    }
  }
]

Response Fields

Each element in the array contains:

Field	Type	Description
id	string	Unique chunk identifier (UUID)
document_id	string	ID of the parent document
content	string	The text content of this chunk
chunk_index	integer	Zero-based position of this chunk within the document
token_count	integer	Number of tokens in the chunk (based on the embedding model's tokenizer)
metadata	object | null	Chunk-level metadata extracted during processing (e.g., section headings)

Errors

Status	Error Type	Description
401	unauthorized	Missing or invalid API key
403	forbidden	API key does not have read permission
404	not-found	No document with the given ID exists in this workspace
429	rate-limit-exceeded	Rate limit exceeded

Example Error Response

{
  "type": "https://api.inherent.systems/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Document 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found in this workspace.",
  "instance": "/api/v1/chunks/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "trace_id": "f6789012-abcd-ef12-3456-789012345678",
  "timestamp": "2026-04-03T12:34:56.789Z"
}