Skip to content

Context API

Create, list, update, version and restore stored contexts.

POST /api/context

Create a context. Identical to POST /api/memory — same handler, same body, same response.

Auth: API key or session.

Body

Field Type Required Default Constraints
project_id string ✅ — Your project key. Created if absent.
agent_id string ✅ — Stored as agent_key.
content string ✅ — 1–8000 characters.
type string fact fact decision preference event constraint relationship
metadata object {} Free-form JSON.
confidence float 0.8 0–1. Stored only; not used in ranking.
importance float 0.5 0–1. 25 % of the retrieval score.

Example

curl -sX POST https://api.venkai.fr/api/context \
  -H "Authorization: Bearer $VENKAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"project_id":"billing-service","agent_id":"planner","type":"decision",
       "importance":0.9,"metadata":{"ticket":"ARCH-14"},
       "content":"We use Postgres, not MongoDB, because the ranking query needs joins."}'

{
  "id": "ctx_cc55e4a7bbc5",
  "org_id": "org_1f200d429c50",
  "project_id": "billing-service",
  "agent_key": "planner",
  "type": "decision",
  "content": "We use Postgres, not MongoDB, because the ranking query needs joins.",
  "confidence": 0.8,
  "importance": 0.9,
  "access_count": 0,
  "last_accessed_at": null,
  "created_at": 1787007131.3763673,
  "updated_at": 1787007131.3763673,
  "metadata": {"ticket": "ARCH-14"},
  "embedding": [0.0, 0.0, 0.30151134457776363, "…"]
}

The write response includes the raw embedding; read responses strip it. Do not depend on it.

Errors

Status When
401 Missing or invalid credential
422 Unknown type, content empty or > 8000 chars, importance/confidence out of [0,1]

GET /api/context/{project_id}

List stored contexts, newest first. Not ranked — use /relevant for prompts.

Auth: API key or session. Unknown project key → 404.

Query parameters

Param Default Notes
type — Exact match on one of the six types
q — Substring filter on content, not a ranking signal
agent — Filter by agent_key
order created_desc Sort order
limit 50 Capped at 200 server-side
offset 0 Pagination

Example

curl -s "https://api.venkai.fr/api/context/billing-service?type=decision&limit=50" \
  -H "Authorization: Bearer $VENKAI_API_KEY"

{
  "project_id": "billing-service",
  "context": [
    {
      "id": "ctx_fd7e76ac9ed0",
      "org_id": "org_ce7930788aae",
      "project_id": "billing-service",
      "agent_key": "planner",
      "type": "constraint",
      "content": "The retrieval endpoint must answer in under 200 ms at p95.",
      "confidence": 0.8,
      "importance": 0.8,
      "access_count": 0,
      "last_accessed_at": null,
      "created_at": 1787007141.8649552,
      "updated_at": 1787007141.8649552,
      "metadata": {}
    }
  ],
  "decisions": [],
  "count": 1,
  "total": 2,
  "offset": 0
}
Field Meaning
context This page of results
decisions The subset of context whose type is decision — a convenience, already inside context
count Size of this page
total Matches after filters — paginate against this
offset Echo of the request

limit=500 silently returns 200. Check count against total.

PATCH /api/context/{context_id}

Update content or metadata. Takes the ctx_… id, not a project key.

curl -sX PATCH https://api.venkai.fr/api/context/ctx_cc55e4a7bbc5 \
  -H "Authorization: Bearer $VENKAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"content":"We use Postgres. Reversed 2026-08: MongoDB is out for good."}'
Field Notes
content Changing it recomputes the embedding and records a version
metadata Replaces the object

Returns the updated context. 404 if the id does not exist or belongs to another organization — the two are indistinguishable by design.

There is no endpoint to delete a single context.

GET /api/context/{context_id}/versions

curl -s https://api.venkai.fr/api/context/ctx_cc55e4a7bbc5/versions \
  -H "Authorization: Bearer $VENKAI_API_KEY"

{"context_id": "ctx_cc55e4a7bbc5", "versions": [ ... ], "count": 1}

Ordered by version number. A context never edited has count: 0.

POST /api/context/{context_id}/restore

curl -sX POST https://api.venkai.fr/api/context/ctx_cc55e4a7bbc5/restore \
  -H "Authorization: Bearer $VENKAI_API_KEY" \
  -H 'Content-Type: application/json' -d '{"version": 1}'

version is an integer ≥ 1. A restore creates a new version entry rather than truncating history. Unknown version → 404.

GET /api/timeline/{project_id}

Chronological view, oldest first.

curl -s "https://api.venkai.fr/api/timeline/billing-service?limit=100" \
  -H "Authorization: Bearer $VENKAI_API_KEY"

{
  "project_id": "billing-service",
  "timeline": [
    {
      "timestamp": 1787007141.8046107,
      "agent": "planner",
      "type": "decision",
      "summary": "We use Postgres, not MongoDB, because the ranking query needs joins.",
      "context_id": "ctx_3f156f85fe3f"
    }
  ]
}

summary is content truncated to 140 characters. Fetch the full record via the list endpoint when you need it. limit defaults to 100.