Skip to content

Projects API

Projects namespace memories inside an organization. You rarely need these endpoints — writing to a project key creates it — but they are how you list, rename and inspect.

GET /api/projects

curl -s https://api.venkai.fr/api/projects -H "Authorization: Bearer $VENKAI_API_KEY"

{
  "projects": [
    {
      "project_id": "billing-service",
      "name": "billing-service",
      "description": null,
      "status": "active",
      "created_at": 1787007141.7951503,
      "contexts": 2,
      "decisions": 1,
      "agents": 1
    }
  ]
}

project_id is your key. contexts, decisions and agents are counts.

Useful for catching the typo case: two near-identical keys, one with a single memory in it, is a project name that was mistyped once.

POST /api/projects

Create a project explicitly. Returns 201.

Field Required Notes
name ✅ 1–200 chars
project_id ≤ 100 chars. Derived from name when omitted. 
curl -sX POST https://api.venkai.fr/api/projects \
  -H "Authorization: Bearer $VENKAI_API_KEY" -H 'Content-Type: application/json' \
  -d '{"name":"Billing Service","project_id":"billing-service"}'

Pass project_id explicitly if agents will hard-code it — do not rely on how a display name is slugified.

PATCH /api/projects/{project_id}

Field Notes
name 1–200 chars
description ≤ 2000 chars
status active or archived

The project key cannot be renamed

project_key is deliberately absent from this endpoint. Deployed agents carry it hard-coded; renaming it would break their calls with a 404 and no migration path. Change the display name instead.

archived is a label. Archived projects still accept writes and still return results.

GET /api/projects/{project_id}/agents

Agents that have written to this project, from the distinct agent_key values on its contexts. Useful for a "who contributed" view.

GET /api/organization

The caller's organization: identity, and aggregate counts across projects.

DELETE /api/organization

Irreversible

Deletes the organization and its data — every project, every memory, every version. There is no undo and no soft-delete. Export first.

GET /api/export

Full export of the organization's data as JSON. The intended companion to the delete above, and the answer to "can I get my data out": yes, one call.

GET /api/impact

Aggregate usage metrics for the organization.

{
  "tokens_stored": 31,
  "total_recalls": 0,
  "avg_memory_chars": 63,
  "unique_agents": 1,
  "types_distribution": {"decision": 1, "constraint": 1},
  "most_accessed": [
    {
      "id": "ctx_3f156f85fe3f",
      "project_id": "billing-service",
      "content_preview": "We use Postgres, not MongoDB, because the ranking query needs joins.",
      "access_count": 0,
      "type": "decision"
    }
  ],
  "knowledge_age_days": 0.0,
  "versions_total": 0
}

Read these carefully before quoting them:

Field What it actually is
tokens_stored An estimate derived from stored characters. Not a measured token count and not a saving.
total_recalls Count of retrieval calls.
most_accessed Ranked by access_count, which retrieval does not increment — so it is near-meaningless until explicit feedback is used.
knowledge_age_days Age of the oldest memory.
avg_memory_chars, unique_agents, types_distribution, versions_total As named.

tokens_stored is a volume figure. It is not evidence of tokens saved, and should never be presented as one — see Evaluation.