Index Build

The Index build endpoint chunks, embeds, and indexes an existing build from its already-parsed content — without re-parsing the document. It is the way out of indexing: 'none': after ingesting or re-processing a source with indexing: 'none', call this endpoint to make the source searchable.

Endpoint overview

HTTP Method

POST

Endpoint URL

https://sources.graphorlm.com/index

Authentication

This endpoint requires authentication using an API token. Include your API token as a Bearer token in the Authorization header.

Learn how to create and manage API tokens in the API Tokens guide.

Request format

Headers

Header	Value	Required
`Authorization`	`Bearer YOUR_API_TOKEN`	Yes
`Content-Type`	`application/json`	Yes

Request body

Send a JSON body with the following fields:

Field	Type	Description	Required
`file_id`	string	Unique identifier of the source whose build should be indexed	Yes
`build_id`	string	Build to index. When omitted, the file’s active build is used. Indexing a non-active build makes it the active build.	No

Behavior

Chunks, embeds, and indexes the build’s persisted partitions — the document is not re-parsed.
Makes the build the source’s active build.
Sets the build’s indexing level to full.
Afterwards, ask, extraction, and prebuilt RAG retrieval see the source, and Get build status reports searchable: true.

The request is synchronous — the response arrives when indexing has finished. For large documents the connection is kept alive with whitespace heartbeats that JSON parsers ignore, so no client changes are needed.

Request example

{
  "file_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

With a specific build:

{
  "file_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "build_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response format

Success response (200 OK)

{
  "file_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "build_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "chunks_indexed": 42,
  "indexing": "full",
  "success": true
}

Response fields

Field	Type	Description
`file_id`	string	The source file ID
`build_id`	string	The build that was indexed (now the source’s active build)
`chunks_indexed`	integer	Number of chunks created and indexed
`indexing`	string	The build’s indexing level after the operation: `full`
`success`	boolean	Whether indexing completed successfully

Code examples

JavaScript/Node.js

const indexBuild = async (apiToken, fileId, buildId = undefined) => {
  const body = buildId ? { file_id: fileId, build_id: buildId } : { file_id: fileId };

  const response = await fetch("https://sources.graphorlm.com/index", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  if (!response.ok) {
    const err = await response.json().catch(() => ({}));
    throw new Error(err.detail || `Index build failed: ${response.status}`);
  }

  return await response.json();
};

// Usage: index the source's active build
const result = await indexBuild(
  "grlm_your_api_token_here",
  "f47ac10b-58cc-4372-a567-0e02b2c3d479"
);
console.log("Chunks indexed:", result.chunks_indexed);

Python

import requests

def index_build(api_token, file_id, build_id=None):
    url = "https://sources.graphorlm.com/index"
    headers = {
        "Authorization": f"Bearer {api_token}",
        "Content-Type": "application/json",
    }
    payload = {"file_id": file_id}
    if build_id:
        payload["build_id"] = build_id
    response = requests.post(url, headers=headers, json=payload, timeout=600)
    response.raise_for_status()
    return response.json()

# Usage: index the source's active build
result = index_build("grlm_your_api_token_here", "f47ac10b-58cc-4372-a567-0e02b2c3d479")
print("Chunks indexed:", result["chunks_indexed"])

cURL

curl -X POST https://sources.graphorlm.com/index \
  -H "Authorization: Bearer grlm_your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{"file_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479"}'

Error responses

Common error codes

Status code	Description
`400`	Indexing is unavailable on the deployment, the build is not in a settled status, the build has no partitions, or the build is already indexed — the response `detail` says which
`404`	Unknown `file_id` or `build_id`

Error response format

{
  "detail": "Human-readable description of the problem"
}

Error examples

Indexing unavailable (400)

Cause: The deployment does not support indexing through this endpoint.
Solution: Check GET https://sources.graphorlm.com/config — see Deployment support.

Build not settled (400)

Cause: The build is still pending or processing.
Solution: Poll Get build status until the build reaches a settled status, then retry.

Build has no partitions (400)

Cause: The build produced no parsed content to index.
Solution: Re-process the source (see Reprocess) and check the build’s error field.

Build already indexed (400)

Cause: The build is already indexed; there is nothing to do.
Solution: None needed — the source is already searchable. The response detail says so.

File or build not found (404)

Cause: The given file_id (or build_id) does not exist in your project.
Solution: Verify the IDs (e.g. from List sources or a previous build status response).

Best practices

Ingest with indexing: 'none' first: Use this endpoint as the second step of a two-phase flow — parse fast without indexing, review the parse results, then index only the sources you keep.
Allow generous timeouts: Indexing is synchronous; large documents take longer. The heartbeats keep the connection alive, but set a generous client timeout anyway.
Verify with build status: After a successful call, Get build status reports searchable: true for the build.

Next steps

Get build status

Confirm the build is now active and searchable: true

Ingest sources

Upload files, URLs, GitHub repos, or YouTube videos — with enrichment and indexing options

Reprocess source

Re-run the ingestion pipeline with a different partition method

List sources

View all sources and their status in your project

Get Started

Data API Options

Endpoint overview

HTTP Method

Endpoint URL

Authentication

Request format

Headers

Request body

Behavior

Request example

Response format

Success response (200 OK)

Response fields

Code examples

JavaScript/Node.js

Python

cURL

Error responses

Common error codes

Error response format

Error examples

Best practices

Next steps

Get build status

Ingest sources

Reprocess source

List sources

​Endpoint overview

HTTP Method

Endpoint URL

​Authentication

​Request format

​Headers

​Request body

​Behavior

​Request example

​Response format

​Success response (200 OK)

​Response fields

​Code examples

​JavaScript/Node.js

​Python

​cURL

​Error responses

​Common error codes

​Error response format

​Error examples

​Best practices

​Next steps

Get build status

Ingest sources

Reprocess source

List sources

Endpoint overview

Authentication

Request format

Headers

Request body

Behavior

Request example

Response format

Success response (200 OK)

Response fields

Code examples

JavaScript/Node.js

Python

cURL

Error responses

Common error codes

Error response format

Error examples

Best practices

Next steps