API Reference

The IntelliRag API provides programmatic access to all platform functionality - managing workspaces and repositories, querying symbols, searching code, and traversing the knowledge graph. The API follows REST conventions and returns JSON responses.

Base URL

All API requests are made to:

https://api.intellirag.io

All endpoints are under the /v1/ path prefix.

Interactive API reference

Explore all endpoints interactively in the API Reference Explorer.

The machine-readable OpenAPI 3.x specification is available at https://api.intellirag.io/openapi.json for generating client libraries or importing into tools like Postman.

Response format

Success responses

Successful responses return the resource directly as a JSON object. Resources are not wrapped in a data envelope.

{
  "id": "w_xxxx",
  "name": "Backend Services",
  "description": "Core backend microservices",
  "created_at": "2024-01-01T00:00:00Z"
}

List responses

Endpoints that return multiple resources include cursor-based pagination metadata:

{
  "items": [
    { "id": "w_xxxx", "name": "Backend Services" },
    { "id": "w_yyyy", "name": "Frontend Apps" }
  ],
  "next_cursor": "eyJ...",
  "has_more": true
}

Error responses

Errors follow the RFC 9457 problem details format:

{
  "status": 400,
  "title": "Bad Request",
  "detail": "workspace_id is required"
}

Field	Description
status	HTTP status code
title	Short human-readable summary of the error type
detail	Specific explanation of what went wrong

Pagination

All list endpoints use cursor-based pagination. To paginate through results, pass the next_cursor value from the previous response as the cursor query parameter.

Parameter	Type	Default	Description
cursor	string	-	Opaque cursor from a previous response’s next_cursor
limit	integer	50	Number of items per page (max 100)

When has_more is false, there are no more pages to fetch.

# First page
curl https://api.intellirag.io/v1/workspaces?limit=10 \
  -H "Authorization: Bearer rag_xxxx"

# Next page
curl "https://api.intellirag.io/v1/workspaces?limit=10&cursor=eyJ..." \
  -H "Authorization: Bearer rag_xxxx"

Rate limits

Rate limits are applied per API key.

Endpoint type	Limit
Read endpoints (GET)	100 requests/second
Write endpoints (POST, PATCH, DELETE)	10 requests/second

When a rate limit is exceeded, the API returns a 429 Too Many Requests response. Back off and retry after a brief delay.

Versioning

The API is versioned via the URL path. All current endpoints are under /v1/. Breaking changes will be introduced under a new version prefix (e.g. /v2/), and previous versions will continue to be supported for a deprecation period.