API Documentation

Base URL: https://api.ctxvault.dev/api/v1

All authenticated endpoints require a Authorization: Bearer cv_... header.

1Authentication

POST/auth/register

Create an account. Returns an API key and a default project. No authentication required.

REQUEST BODY

{
  "name": "Acme Inc",
  "email": "dev@acme.com"
}

RESPONSE

{
  "api_key": "cv_abc123...",
  "project_slug": "acme-inc",
  "project_name": "Acme Inc's Project",
  "message": "Save your API key — it cannot be recovered."
}

2Projects

GET/projectsAuth Required

List all projects you have access to.

RESPONSE

[
  {
    "id": "uuid",
    "slug": "my-app",
    "name": "My App",
    "created_at": "2025-01-01T00:00:00Z"
  }
]

POST/projectsAuth Required

Create a new project. Requires ADMIN role.

REQUEST BODY

{
  "name": "My App",
  "slug": "my-app",
  "description": "Optional description"
}

RESPONSE

{
  "id": "uuid",
  "slug": "my-app",
  "name": "My App"
}

3Memory

POST/memory/candidatesAuth Required

Push memory candidates. Items are embedded and stored for review. Types: decision, convention, pattern, lesson, snippet, reference.

REQUEST BODY

{
  "project_slug": "my-app",
  "items": [
    {
      "type": "decision",
      "title": "Use PostgreSQL",
      "content": "Chose PostgreSQL for pgvector support.",
      "importance": 8,
      "tags": ["database", "infrastructure"]
    }
  ]
}

RESPONSE

{
  "candidate_ids": ["uuid1", "uuid2"]
}

POST/memory/searchAuth Required

Semantic search across memory items using vector similarity.

REQUEST BODY

{
  "project_slug": "my-app",
  "query": "which database did we choose?",
  "k": 5
}

RESPONSE

{
  "results": [
    {
      "id": "uuid",
      "title": "Use PostgreSQL",
      "type": "decision",
      "score": 0.92,
      "status": "verified"
    }
  ]
}

GET/memory?project=my-appAuth Required

List memory items with optional filters: status, type.

RESPONSE

{
  "items": [...],
  "total": 42,
  "page": 1
}

GET/memory/{id}Auth Required

Get a single memory item by ID.

RESPONSE

{
  "id": "uuid",
  "type": "decision",
  "title": "Use PostgreSQL",
  "content": "...",
  "status": "verified",
  "importance": 8,
  "tags": ["database"],
  "created_at": "2025-01-01T00:00:00Z"
}

POST/memory/{id}/verifyAuth Required

Mark a memory item as verified. Requires REVIEWER role.

RESPONSE

{ "message": "Memory verified" }

POST/memory/{id}/pinAuth Required

Pin a memory item (prevents decay). Requires REVIEWER role.

RESPONSE

{ "message": "Memory pinned" }

POST/memory/{id}/deprecateAuth Required

Deprecate a memory item. Requires REVIEWER role.

RESPONSE

{ "message": "Memory deprecated" }

4Context Pack

POST/context-packAuth Required

Generate a context pack — a token-budgeted bundle of relevant memories ready to inject into your LLM prompt.

REQUEST BODY

{
  "project_slug": "my-app",
  "query": "how do we handle authentication?",
  "max_tokens": 2000
}

RESPONSE

{
  "pack": "## Project Context\n\n### Decisions\n- Use JWT for auth...",
  "token_count": 1850,
  "truncated": false,
  "items": [...]
}

5API Keys

POST/api-keysAuth Required

Create a new API key. Requires ADMIN role. Roles: READER, REVIEWER, ADMIN.

REQUEST BODY

{
  "name": "ci-pipeline",
  "role": "READER",
  "allowed_projects": ["my-app"]
}

RESPONSE

{
  "id": "uuid",
  "key": "cv_...",
  "prefix": "cv_abc12",
  "name": "ci-pipeline",
  "role": "READER",
  "message": "Save this key — it cannot be recovered"
}

GET/api-keysAuth Required

List all API keys. Requires ADMIN role.

RESPONSE

[
  {
    "id": "uuid",
    "prefix": "cv_abc12",
    "name": "ci-pipeline",
    "role": "READER",
    "last_used_at": "2025-01-01T00:00:00Z"
  }
]

DELETE/api-keys/{id}Auth Required

Revoke an API key. Requires ADMIN role.

RESPONSE

{ "message": "API key revoked" }

6Health

GET/health

Check server health. Returns status of database, pgvector, and object storage.

RESPONSE

{
  "status": "ok",
  "checks": {
    "db": "ok",
    "pgvector": "ok",
    "storage": "ok"
  }
}