Context & Knowledge API

The Context API manages per-session conversation state and file attachments. The Knowledge API manages the Qdrant-backed vector store collections used for RAG (Retrieval-Augmented Generation).

All endpoints require authentication. See Configuration Reference for auth options.

---

Context API

Context endpoints are under the /context prefix. They manage conversation history and blob attachments scoped to a (session_id, user_id, assistant_id, agentspace_id) tuple stored in Redis.

Context headers

All /context endpoints (except /context/persist) require these headers to identify the session:

| Header | Description | |---|---| | session-id | Session identifier | | user-id | User identifier | | assistant-id | Agent identifier | | agentspace-id | Agentspace identifier |

---

GET /context/retrieve

Retrieve the full conversation history and blob metadata for a session.

Query parameters

| Parameter | Type | Default | Description | |---|---|---|---| | limit | int | 0 | Maximum number of messages to return. 0 = all messages. Max 100. | | offset | int | -1 | Starting offset. -1 = from the end (most recent). |

Response — 200 OK

{
  "user_id": "user-1",
  "session_id": "session-abc",
  "messages": [
    {"type": "human", "content": "What is the status of ticket INC-1234?"},
    {"type": "ai", "content": "Ticket INC-1234 is currently Open."}
  ],
  "blobs": []
}

| Field | Type | Description | |---|---|---| | user_id | string | User identifier | | session_id | string | Session identifier | | messages | Message[] | Conversation messages in chronological order | | blobs | Blob[] | File attachments associated with this session |

Example

curl "http://localhost:8080/context/retrieve?limit=20" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "session-id: session-abc" \
  -H "user-id: user-1" \
  -H "assistant-id: my-agent" \
  -H "agentspace-id: default"

---

POST /context/blob/upload

Upload a file and attach it to the current session context. The file is stored in S3-compatible blob storage and its metadata is registered in Redis.

The agent will have access to the file content during inference via {{ attachment_context }} in the system prompt.

Request

multipart/form-data with a single file field.

Supported file types: PDF, DOCX, TXT, and other formats supported by the configured document loaders.

Size limit: MAX_FILE_CONTENT_SIZE (default: 20 MB).

Response — 200 OK

{
  "uuid": "blob-abc123",
  "filename": "report.pdf",
  "content_type": "application/pdf",
  "content_size": 204800
}

| Field | Type | Description | |---|---|---| | uuid | string | Blob identifier — use this to download or reference the blob | | filename | string | Original filename | | content_type | string | MIME type | | content_size | int | File size in bytes |

Error responses

| Status | Condition | |---|---| | 400 | File type not supported | | 400 | File exceeds MAX_FILE_CONTENT_SIZE | | 500 | S3 storage error |

Example

curl -X POST http://localhost:8080/context/blob/upload \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "session-id: session-abc" \
  -H "user-id: user-1" \
  -H "assistant-id: my-agent" \
  -H "agentspace-id: default" \
  -F "file=@report.pdf"

---

GET /context/blob/download/{blob_id}

Download a blob from the session context.

Path parameters

| Parameter | Type | Description | |---|---|---| | blob_id | string | The blob UUID from the upload response |

Query parameters

| Parameter | Type | Default | Description | |---|---|---|---| | keep | bool | true | If false, removes the blob from the session context after download | | response_base64 | bool | false | If true, returns base64-encoded content instead of raw bytes |

Response — 200 OK

Raw file bytes with appropriate Content-Type and Content-Disposition headers.

Response headers:

• Content-Disposition: attachment; filename="<filename>"
• X-Blob-ID: <blob_id>

Error responses

| Status | Condition | |---|---| | 404 | Session context not found | | 404 | Blob not found in session context | | 500 | S3 download error |

Example

# Download and save
curl -O -J "http://localhost:8080/context/blob/download/blob-abc123?keep=true" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "session-id: session-abc" \
  -H "user-id: user-1" \
  -H "assistant-id: my-agent" \
  -H "agentspace-id: default"

---

POST /context/persist

Persist a conversation to Redis. This is an internal endpoint called by the runtime during the ContextPersistence stage — not intended for direct client use.

Caution

This endpoint is called automatically by the agent execution pipeline. Calling it directly may corrupt session state.

---

Knowledge API

Knowledge endpoints are under the /knowledge prefix. They manage the Qdrant vector store collections (called topics) and the files indexed within them. Topics are the RAG knowledge bases that agents query during inference.

Files

File endpoints manage the document library — files uploaded to S3 storage and registered in PostgreSQL, ready to be indexed into topics.

---

GET /knowledge/files

List all files in the document library.

Query parameters

| Parameter | Type | Default | Description | |---|---|---|---| | limit | int | 100 | Maximum results | | offset | int | 0 | Pagination offset | | is_active | bool | null | Filter by active status |

Response — 200 OK

[
  {
    "id": 1,
    "blob_id": "blob-abc123",
    "name": "product-manual.pdf",
    "content_type": "application/pdf",
    "size": 204800,
    "checksum": "sha256:abc...",
    "is_active": true,
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
]

---

POST /knowledge/files/upload

Upload a document to the file library. The file is stored in S3 and registered in PostgreSQL. It is not yet indexed into any topic — use PUT /knowledge/topics/{topic_id}/add/{file_id} to index it.

Request

multipart/form-data with a single file field.

Supported formats: PDF, DOCX, TXT, and other formats supported by the document loaders.

Size limit: MAX_FILE_CONTENT_SIZE (default: 20 MB).

Response — 200 OK

{
  "id": 1,
  "blob_id": "blob-abc123",
  "name": "product-manual.pdf",
  "content_type": "application/pdf",
  "size": 204800,
  "checksum": "sha256:abc...",
  "is_active": true,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z"
}

Error responses

| Status | Condition | |---|---| | 400 | File type not supported | | 400 | File exceeds MAX_FILE_CONTENT_SIZE |

Example

curl -X POST http://localhost:8080/knowledge/files/upload \
  -H "Authorization: Bearer $API_TOKEN" \
  -F "file=@product-manual.pdf"

---

GET /knowledge/files/download/{file_id}

Download a file from the library by its database ID.

Path parameters

| Parameter | Type | Description | |---|---|---| | file_id | int | Database file ID |

Response — 200 OK

Raw file bytes with Content-Disposition and X-Blob-ID headers.

Error responses

| Status | Condition | |---|---| | 404 | File not found | | 500 | S3 download error |

---

DELETE /knowledge/files/delete/{file_id}

Delete a file from the library and remove it from S3 storage.

Caution

Deleting a file does not automatically remove its vectors from Qdrant topics. Remove the file from topics first using PUT /knowledge/topics/{topic_id}/remove/{file_id}.

Path parameters

| Parameter | Type | Description | |---|---|---| | file_id | int | Database file ID |

Response — 200 OK

The deleted FileInDetail object.

Error responses

| Status | Condition | |---|---| | 404 | File not found |

---

Topics

Topics are named Qdrant vector store collections. Each topic maps to a Qdrant collection and a PostgreSQL record. Agents reference topics by collection_id in their knowledge_base configuration.

---

GET /knowledge/topics

List all topics.

Query parameters

| Parameter | Type | Default | Description | |---|---|---|---| | limit | int | 100 | Maximum results | | offset | int | 0 | Pagination offset | | is_active | bool | null | Filter by active status |

Response — 200 OK

[
  {
    "id": 1,
    "name": "Product Documentation",
    "external_collection_id": "product-docs",
    "description": "Product manuals and release notes",
    "files": [{"id": 1, "name": "product-manual.pdf"}],
    "tags": [{"name": "product"}],
    "is_active": true,
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
]

---

GET /knowledge/topics/{topic_id}

Get a single topic by ID.

Error responses

| Status | Condition | |---|---| | 404 | Topic not found |

---

POST /knowledge/topics

Create a new topic and its corresponding Qdrant collection.

Request body

{
  "name": "Product Documentation",
  "external_collection_id": "product-docs",
  "description": "Product manuals and release notes",
  "vector_size": 1536,
  "distance_metric": "Cosine"
}

| Field | Type | Required | Description | |---|---|---|---| | name | string | Yes | Human-readable topic name | | external_collection_id | string | Yes | Qdrant collection name — must be unique | | description | string | No | Topic description | | vector_size | int | Yes | Embedding dimension (e.g., 1536 for OpenAI text-embedding-3-small) | | distance_metric | string | Yes | Qdrant distance metric: Cosine, Dot, Euclid |

Response — 200 OK

The created TopicInDetail object.

Error responses

| Status | Condition | |---|---| | 400 | Topic with this name or external_collection_id already exists | | 503 | Qdrant unavailable |

Example

curl -X POST http://localhost:8080/knowledge/topics \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Documentation",
    "external_collection_id": "product-docs",
    "vector_size": 1536,
    "distance_metric": "Cosine"
  }'

---

DELETE /knowledge/topics/{topic_id}

Delete a topic, its Qdrant collection, and all indexed vectors.

Error responses

| Status | Condition | |---|---| | 404 | Topic not found | | 503 | Qdrant unavailable |

---

PUT /knowledge/topics/{topic_id}/add/{file_id}

Index a file into a topic. Splits the document into chunks, generates embeddings, and upserts them into the Qdrant collection. Runs as a background task.

Path parameters

| Parameter | Type | Description | |---|---|---| | topic_id | int | Topic database ID | | file_id | int | File database ID |

Query parameters

| Parameter | Type | Default | Description | |---|---|---|---| | preview | int | 0 | If > 0, return the first N chunks without indexing (dry run) |

Request body

Text splitter configuration:

{
  "chunk_size": 1000,
  "chunk_overlap": 200,
  "separators": ["\n\n", "\n", " "]
}

| Field | Type | Default | Description | |---|---|---|---| | chunk_size | int | 1000 | Maximum characters per chunk | | chunk_overlap | int | 200 | Overlap between consecutive chunks | | separators | string[] | ["\n\n", "\n", " "] | Split separators in priority order |

Response — 201 Created

{
  "total_documents": 42,
  "documents": [
    {
      "page_content": "Chapter 1: Installation...",
      "metadata": {"source": "product-manual.pdf", "blob_id": "blob-abc123"}
    }
  ]
}

When preview > 0, returns the first N chunks without indexing.

Error responses

| Status | Condition | |---|---| | 400 | File already indexed in this topic | | 404 | File or topic not found | | 500 | Qdrant vector store error |

Example

# Index a file into a topic
curl -X PUT "http://localhost:8080/knowledge/topics/1/add/1" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chunk_size": 1000, "chunk_overlap": 200}'

# Preview chunks without indexing
curl -X PUT "http://localhost:8080/knowledge/topics/1/add/1?preview=5" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chunk_size": 1000, "chunk_overlap": 200}'

---

PUT /knowledge/topics/{topic_id}/remove/{file_id}

Remove a file’s vectors from a topic. Deletes all Qdrant points where metadata.blob_id matches the file’s blob ID.

Error responses

| Status | Condition | |---|---| | 400 | File not in this topic | | 404 | Topic not found |

---

POST /knowledge/topics/search/{topic_id}

Search a topic’s vector store with a query string.

Path parameters

| Parameter | Type | Description | |---|---|---| | topic_id | int | Topic database ID |

Request body

{
  "query": "How do I install the product?",
  "search_type": "similarity",
  "search_kwargs": {"k": 5},
  "doc_separator": "\n\n",
  "doc_template": "{page_content}"
}

| Field | Type | Default | Description | |---|---|---|---| | query | string | required | Search query | | search_type | string | "similarity" | Qdrant search type | | search_kwargs | dict | {"k": 5} | Search parameters (e.g., k for top-K results) | | doc_separator | string | "\n\n" | Separator between returned documents | | doc_template | string | "{page_content}" | Template for formatting each document |

Response — 200 OK

Array of SearchResponse objects with matching document chunks and metadata.

Error responses

| Status | Condition | |---|---| | 404 | Topic not found |

---

PUT /knowledge/topics/{topic_id}/update

Update a topic’s name or description.

Request body

{
  "name": "Updated Topic Name",
  "description": "Updated description"
}

Error responses

| Status | Condition | |---|---| | 400 | Topic with this name already exists | | 404 | Topic not found |

---

PUT /knowledge/topics/{topic_id}/tag

Add a tag to a topic.

Request body

{"name": "product"}

---

PUT /knowledge/topics/{topic_id}/untag

Remove a tag from a topic.

Request body

{"name": "product"}

---

Connecting topics to agents

Once a topic is created and indexed, reference it in the agent’s knowledge_base configuration:

{
  "profile": {
    "knowledge_base": [
      {
        "collection_id": "product-docs",
        "search_mode": "always",
        "top_k": 5
      }
    ]
  }
}

| search_mode | Behavior | |---|---| | "always" | Retrieve context on every inference call | | "on_demand" | Expose as a search tool the LLM can call explicitly |

See Agent Configuration for the full knowledge_base schema.

---

Related pages

• Inference Endpoints — submit inference requests and stream results
• Agent Configuration — configure knowledge_base in agent specs
• Configuration Reference — Qdrant and S3 settings