API Documentation

Capsule creation requires a Bearer token. Get one via the signup endpoint. Keys use the ak_ prefix.

Authorization: Bearer ak_your_api_key

Fetch endpoints are public — no authentication required.

Create a context capsule. Auth required. Rate limit: 60/min per API key.

Request

curl -X POST https://www.contextcapsule.ai/v1/capsules \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Refactored auth module",
    "decisions": ["Chose RS256 over HS256"],
    "next_steps": ["Add refresh tokens"],
    "payload": {"files": ["auth.ts"]},
    "refs": {"workflow_id": "wf_123"},
    "expires_in": 3600
  }'

Response (201)

{
  "id": "cap_...",
  "short_url": "https://www.contextcapsule.ai/capsule/cap_...",
  "expires_at": "2025-01-01T12:00:00.000Z",
  "request_id": "req_..."
}

Fetch a capsule by ID. Public. Rate limit: 120/min per IP.

curl https://www.contextcapsule.ai/v1/capsules/cap_abc123

Response (200)

{
  "id": "cap_abc123",
  "summary": "Refactored auth module",
  "decisions": ["Chose RS256 over HS256"],
  "next_steps": ["Add refresh tokens"],
  "payload": {"files": ["auth.ts"]},
  "refs": {"workflow_id": "wf_123"},
  "audience": null,
  "created_at": "2025-01-01T11:00:00.000Z",
  "expires_at": "2025-01-01T12:00:00.000Z"
}

Short URL also works: GET /capsule/:id

Get a free API key. Rate limit: 5/min per IP.

curl -X POST https://www.contextcapsule.ai/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Response (201)

{
  "api_key": "ak_...",
  "message": "Store this key securely — it cannot be retrieved later."
}

Hourly cleanup of expired capsules. Protected by a shared secret.

curl -X POST https://www.contextcapsule.ai/cron/cleanup \
  -H "Authorization: Bearer CRON_SECRET"

Response (200)

{"deleted": 42}

Refs Object

All errors return a JSON body with error, message, and request_id.

Use Context Capsule from any MCP-compatible client:

npx -y @contextcapsule/mcp-server

Tools: create_capsule, fetch_capsule, signup