Contexts

Contexts let you attach curated knowledge — documents, notes, web pages, or chain outputs — to your account or workspace. Once ingested, contexts are semantically indexed and automatically injected into your AI twin's prompt pipeline.

Base path

/api/v1/agents/contexts

Authentication

All endpoints require a valid JWT Bearer token.

export BASE_URL="https://api.chainabit.com/api/v1"
export TOKEN="your-access-token"
export WORKSPACE_ID="your-workspace-id"

---

Endpoints

Method	Path	Description
GET	/agents/contexts	List contexts
GET	/agents/contexts/:id	Get a context by ID
POST	/agents/contexts	Create a context
PATCH	/agents/contexts/:id	Update title or description
DELETE	/agents/contexts/:id	Delete a context
POST	/agents/contexts/search	Semantic search over contexts

---

GET /agents/contexts

List contexts owned by your account.

Request

Query parameters

Parameter	Type	Default	Description
limit	number	20	Records per page
offset	number	0	Pagination offset
workspaceId	string	—	Filter to a specific workspace

Response

{
  "data": [
    {
      "id": "ctx_01...",
      "title": "Q1 Strategy",
      "description": "Leadership OKR notes",
      "status": "ready",
      "content_summary": "A concise AI-generated summary...",
      "created_at": "2026-04-01T10:00:00Z"
    }
  ],
  "meta": { "total": 12, "limit": 10, "offset": 0 }
}

Code Example

curl "$BASE_URL/agents/contexts?limit=10" \
  -H "Authorization: Bearer $TOKEN"

---

GET /agents/contexts/:id

Get a single context by ID.

Response

Returns 404 if the context does not exist or belongs to another account.

Code Example

curl "$BASE_URL/agents/contexts/ctx_01..." \
  -H "Authorization: Bearer $TOKEN"

---

POST /agents/contexts

Create a new context. Ingestion — AI summarisation and embedding — runs asynchronously. The returned record has status: "processing".

Request

Query parameters

Parameter	Type	Description
workspaceId	string	Optional — attach to a workspace

Request body

Field	Type	Required	Description
title	string	Yes	Display name (max 200 chars)
description	string	No	Optional description (max 500 chars)
sourceType	string	Yes	document, note, web, or chain_output
rawContent	string	No	Text content for document, note, chain_output (max 100 000 chars)
url	string	No	URL for web sources (max 2048 chars)
chainId	string	No	Chain ID for chain_output sources

Response

{
  "data": {
    "id": "ctx_01...",
    "title": "Q1 Strategy",
    "status": "processing",
    "created_at": "2026-04-11T09:00:00Z"
  }
}

Code Examples

Example — document

curl -X POST "$BASE_URL/agents/contexts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q1 Strategy",
    "description": "Leadership OKR notes",
    "sourceType": "document",
    "rawContent": "In Q1 we aim to grow revenue by 30%..."
  }'

Example — web page

curl -X POST "$BASE_URL/agents/contexts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Competitor Analysis",
    "sourceType": "web",
    "url": "https://example.com/analysis"
  }'

---

PATCH /agents/contexts/:id

Update the title and/or description of a context.

Request

Request body

Field	Type	Description
title	string	New title (max 200 chars)
description	string | null	New description, or null to clear

Code Example

curl -X PATCH "$BASE_URL/agents/contexts/ctx_01..." \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Q1 Strategy — Revised" }'

---

DELETE /agents/contexts/:id

Delete a context. Soft-delete — the record is hidden but not physically removed.

Response

{ "data": { "deleted": true } }

Code Example

curl -X DELETE "$BASE_URL/agents/contexts/ctx_01..." \
  -H "Authorization: Bearer $TOKEN"

---

POST /agents/contexts/search

Semantic search over your ready contexts. Results are ranked by a combination of cosine similarity and recency.

Request

Request body

Field	Type	Required	Description
query	string	Yes	Natural language search query (max 1000 chars)
topK	number	No	Max results, 1–20 (default 3)
workspaceId	string	No	Scope to a specific workspace

Response

{
  "data": [
    {
      "id": "ctx_01...",
      "title": "Q1 Strategy",
      "contentSummary": "A concise AI-generated summary...",
      "score": 0.873
    }
  ]
}

Code Example

curl -X POST "$BASE_URL/agents/contexts/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Q1 product strategy",
    "topK": 5
  }'

---

Context statuses

Status	Meaning
processing	Ingestion running — not yet searchable
ready	Indexed and available for semantic search
failed	Ingestion failed — not searchable

---

Notes

• Only ready contexts appear in search results.
• Contexts with status: "processing" are still listed by GET /agents/contexts and GET /agents/contexts/:id.
• Deleting a context removes it from future prompt injections immediately, even if the twin was previously using it.