API Documentation

Looking for the primary product? Install the local-first Context Capsule Agent Skill. It requires no account or API key. Use this API only when you explicitly need a short-lived URL for another machine or person.

npx skills add Johnny-Z13/context-capsule --skill contextcapsule-handoff

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. Anyone with a capsule URL can read it. Do not put secrets, credentials, private source, or customer data in capsule content. Upload only with the user’s explicit consent.

Create a public-by-URL, short-lived capsule. Auth required. Rate limit: 60/min per API key. Free tier: 500 capsules per 30 days (429 quota_exceeded when reached). Default expiry is 24 hours.

Request

curl -X POST https://www.contextcapsule.ai/v1/capsules \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Refresh-token migration implemented; staging is not verified",
    "decisions": ["Keep the legacy endpoint for three consumers"],
    "next_steps": ["Run the staging smoke test", "Ask before release"],
    "payload": {"verification": [{"command": "npm test", "result": "71 passed", "source": "observed"}]},
    "refs": {"receipt_ids": []},
    "expires_in": 86400
  }'

Response (201)

{
  "capsule_id": "cap_...",
  "summary": "Refresh-token migration implemented; staging is not verified",
  "decisions": ["Keep the legacy endpoint for three consumers"],
  "next_steps": ["Run the staging smoke test", "Ask before release"],
  "capsule_url": "https://www.contextcapsule.ai/capsule/cap_...",
  "created_at": "2026-04-03T12:00:00.000Z",
  "expires_at": "2026-04-04T12:00:00.000Z",
  "idempotency_key": null
}

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

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

Response (200)

{
  "capsule_id": "cap_abc123",
  "summary": "Refresh-token migration implemented; staging is not verified",
  "decisions": ["Keep the legacy endpoint for three consumers"],
  "next_steps": ["Run the staging smoke test", "Ask before release"],
  "payload": {"verification": [{"command": "npm test", "result": "71 passed", "source": "observed"}]},
  "refs": {"receipt_ids": []},
  "created_at": "2026-04-03T12:00:00.000Z",
  "expires_at": "2026-04-04T12: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.

The MCP server is optional hosted transport for MCP-compatible clients. Prefer the local Agent Skill for normal coding handoffs.

npx -y @contextcapsule/mcp-server

Tools: create_capsule, fetch_capsule, signup