API Reference

All endpoints require a Bearer token API key: Authorization: Bearer rag_your_key

Base URL

https://brain.aistack.run/api/v1

Cloudflare AutoRAG Compatibility

Brain also responds to Cloudflare-style URLs for drop-in migration:

https://brain.aistack.run/api/v1/accounts/{accountId}/autorag/rags/{ragName}/{endpoint}

See the Migrating from Cloudflare AutoRAG guide for details.

Authentication

All requests must include an API key in the Authorization header:

Authorization: Bearer rag_your_api_key

API keys are scoped to a single project. Create them from the API Keys page in your project dashboard.

Permission	Access
`read`	Search endpoints (`/search`, `/ai-search`)
`write`	All endpoints including document management

POST /search

Vector search only — returns ranked document chunks without AI generation. When hybrid search is enabled in project settings, BM25 keyword search runs in parallel and results are merged.

Request body:

{
  "query": "string",
  "max_num_results": 10,
  "score_threshold": 0.3,
  "include_steps": false,
  "filters": {
    "type": "and",
    "filters": [
      { "key": "folder", "value": "docs/" }
    ]
  }
}

Parameter	Type	Default	Description
`query`	string	required	The search query
`max_num_results`	number	Project setting	Maximum chunks to return
`score_threshold`	number	Project setting (`0.3`)	Minimum similarity score (0-1)
`include_steps`	boolean	`false`	Include internal step trace in the response
`filters`	object	`null`	Metadata filters (see Filtering)

Response:

{
  "success": true,
  "result": {
    "object": "vector_store.search_results.page",
    "search_query": "string",
    "data": [
      {
        "file_id": "uuid",
        "filename": "docs/guide.md",
        "score": 0.95,
        "attributes": { "folder": "docs/" },
        "content": [{ "id": "chunk-uuid", "type": "text", "text": "..." }]
      }
    ],
    "has_more": false,
    "next_page": null
  }
}

When include_steps is true, the response also includes a steps array with timing and metadata for each internal operation (embedding, vector search, BM25 search, etc.).

POST /ai-search

Vector search + LLM generation. When hybrid search is enabled, BM25 keyword search runs alongside vector search.

Request body:

{
  "query": "string",
  "max_num_results": 10,
  "score_threshold": 0.3,
  "stream": false,
  "include_steps": false
}

Parameter	Type	Default	Description
`query`	string	required	The search query
`max_num_results`	number	Project setting	Maximum chunks to return
`score_threshold`	number	Project setting (`0.3`)	Minimum similarity score (0-1)
`stream`	boolean	`false`	Enable SSE streaming responses
`include_steps`	boolean	`false`	Include internal step trace
`filters`	object	`null`	Metadata filters

Response (non-streaming):

{
  "success": true,
  "result": {
    "object": "vector_store.search_results.page",
    "search_query": "string",
    "response": "AI-generated answer...",
    "data": [...],
    "has_more": false,
    "next_page": null
  }
}

Streaming (SSE)

When stream: true, returns SSE with Content-Type: text/event-stream. Events are sent in the following order:

1. Search results — sent first with all matched documents:

data: {"type":"search_results","data":[...],"search_query":"..."}

2. Thinking — reasoning/thinking tokens from the model (if supported):

data: {"type":"thinking","text":"Let me analyze the documents..."}

3. Text — the generated answer, streamed incrementally:

data: {"type":"text","text":"Based on the documents, "}
data: {"type":"text","text":"the answer is..."}

4. Steps — internal step trace (only if include_steps: true):

data: {"type":"steps","steps":[...]}

5. Error — sent if generation fails (instead of closing the connection):

data: {"type":"error","error":"Provider returned an error"}

6. Done — always sent last:

data: [DONE]

GET /documents

List all documents for the project.

Query params:

Param	Type	Default	Description
`limit`	number	50	Max results (1-100)
`prefix`	string	—	Filter by filename prefix (S3-style), e.g. `docs/`

Example:

# List all documents in the "docs/" folder
GET /documents?prefix=docs/&limit=20

Response:

{
  "success": true,
  "result": [
    {
      "id": "uuid",
      "filename": "docs/guide.md",
      "content_type": "text/markdown",
      "status": "indexed",
      "attributes": { "folder": "docs/" },
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ]
}

POST /documents

Upload a document. Supports multipart form data or JSON.

Multipart:

file — File content
filename — Path (e.g., docs/guide.md)
attributes — JSON string of custom metadata

JSON body:

{
  "filename": "docs/guide.md",
  "content": "Document text content...",
  "content_type": "text/markdown",
  "attributes": { "author": "Alice" }
}

Response:

{
  "success": true,
  "result": {
    "id": "uuid",
    "filename": "docs/guide.md",
    "status": "pending"
  }
}

After upload, the document is queued for indexing. Check status via GET /documents/{id} or the Jobs API.

{
  "content": "Updated document text content..."
}

Response:

{
  "success": true,
  "result": {
    "id": "uuid",
    "filename": "docs/guide.md",
    "content_type": "text/markdown",
    "status": "indexed",
    "attributes": { "author": "Alice" },
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-15T12:00:00Z"
  }
}

Notes:

Only updates content, not filename or attributes
Does not automatically re-index — call PATCH /sync or re-upload if you need updated embeddings
Maximum content size: 10 MB
If the document was stored as an S3 object, it will be converted to inline storage

{
  "success": false,
  "errors": [
    { "code": 401, "message": "Invalid or missing API key" }
  ]
}

Common error codes:

Code	Description
`401`	Invalid or missing API key
`403`	Insufficient permissions (e.g., `read` key trying to upload)
`404`	Resource not found
`422`	Invalid request body
`500`	Internal server error

API Reference

API Reference

Base URL

Cloudflare AutoRAG Compatibility

Authentication

POST /search

POST /ai-search

Streaming (SSE)

GET /documents

POST /documents

GET /documents/{id}

DELETE /documents/{id}

PUT /documents/{id}

PATCH /sync

GET /jobs

GET /jobs/{id}

GET /jobs/{id}/logs

Error Responses

On this page