HTTP API

The worker exposes a local HTTP API at http://localhost:3848. It’s the lowest-level surface — the CLI and MCP server both sit on top of it. Localhost-only by default, no auth required.

Conventions

  • Base URL: http://127.0.0.1:3848 (configurable via workerPort)
  • Content type: application/json for all requests and responses
  • Auth: none. Bind to 127.0.0.1 only — if you expose to a network, add a reverse proxy with auth in front.
  • CORS: not set by default. Do not call this API directly from an untrusted browser context.

Health

GET/api/health

Sanity check. Returns the worker status and a savings overview snapshot.

responsejson
{
  "ok": true,
  "dbPath": "~/.contextpilot/contextpilot.db",
  "savings": {
    "estimatedTokensSaved": 340210,
    "estimatedCostSavedUsd": 4.20
  }
}

Hooks

POST/api/hook

Ingest one hook event. Body matches the hook event schema.

requestjson
{
  "kind": "tool_use",
  "agent": "claude",
  "projectRoot": "/home/me/repo",
  "sessionId": "sess_abc",
  "toolName": "edit_file",
  "input": { "filePath": "src/auth.ts", "diff": "..." },
  "timestamp": 1716422400000
}
responsejson
{
  "ok": true,
  "ok": true
}
POST/api/hooks/batch

Ingest many events at once. Use when your hook fires more than ~10 events/second.

requestjson
{ "events": [ /* HookEvent[] */ ] }

Memories

GET/api/memories
limit·number

Max rows to return. Default 50. Cap 500.

responsejson
{
  "memories": [
    {
      "id": "mem_e7f3a1",
      "type": "file_edit",
      "title": "Added Stripe webhook validation",
      "content": "...",
      "files": ["src/api/payments/webhook.ts"],
      "confidence": 0.94,
      "reuseCount": 4,
      "estimatedTokens": 3200,
      "estimatedTokensSaved": 12800,
      "estimatedCostUsd": 0.0096,
      "estimatedCostSavedUsd": 0.0384,
      "archived": false,
      "createdAt": 1716422400000
    }
  ]
}
GET/api/memory/:id

Fetch one full memory by ID.

PATCH/api/memory/:id
title·string

New title. Optional.

content·string

New content. Optional.

confidence·number (0-1)

Manually override the confidence score. Useful for pinning critical memories.

archived·boolean

Set true to archive, false to unarchive.

DELETE/api/memory/:id

Archives the memory.

POST/api/memory

Create a manual memory. Same as MCP contextpilot_remember.

requestjson
{
  "projectRoot": "/home/me/repo",
  "title": "Auth uses JWT exp claim",
  "content": "We standardized on exp, not iat.",
  "files": ["src/auth/middleware.ts"]
}

Search

GET/api/search

Full-text search across memory title and content. Uses SQLite FTS5 under the hood — fast, ranked, supports prefix queries.

q·stringrequired

The query string. Supports FTS5 syntax: quoted phrases, + for required terms, - for excluded.

limit·number

Default 8. Cap 50.

examplebash
curl 'http://127.0.0.1:3848/api/search?q=stripe+webhook&limit=3'

Sessions

GET/api/sessions
limit·number

Default 50. Cap 500.

responsejson
{
  "sessions": [
    {
      "id": "sess_abc",
      "projectId": "proj_xyz",
      "agent": "claude",
      "model": "claude-sonnet-4-6",
      "startedAt": 1716422400000,
      "endedAt":   1716423200000,
      "estimatedTokens": 45200,
      "estimatedCostUsd": 0.34
    }
  ]
}

Projects

GET/api/projects

List every project ctxpilot has captured events for.

responsejson
{
  "projects": [
    { "id": "proj_xyz", "name": "my-app", "rootPath": "/home/me/repo", "lastSeenAt": 1716422400000 }
  ]
}

Events

GET/api/events

Recent ingest events. Used by contextpilot events.

limit·number

Default 50. Cap 500.

responsejson
{
  "events": [
    {
      "id": "evt_5f2",
      "sessionId": "sess_abc",
      "agent": "claude",
      "eventKind": "tool_use",
      "toolName": "edit_file",
      "status": "stored",
      "memoryId": "mem_e7f3a1",
      "processedMs": 4,
      "createdAt": 1716422401200
    }
  ]
}

Analytics

GET/api/analytics/overview

All-time savings rollup. Same data shown by contextpilot status.

responsejson
{
  "estimatedTokensSpent": 1248321,
  "estimatedTokensSaved": 340210,
  "estimatedCostSpentUsd": 12.40,
  "estimatedCostSavedUsd": 4.20,
  "repeatedReads": 847,
  "memoriesCreated": 847,
  "memoriesReused": 213,
  "projectedMonthlySavingsUsd": 16.80
}
GET/api/analytics/savings
limit·number

How many savings traces to return. Default 10.

Returns the top-reused memories with proof and recommendation strings — what powers contextpilot savings.

GET/api/analytics/waste

Findings of repeated reads used by CLI waste reports.

responsejson
{
  "findings": [
    {
      "filePath": "src/auth/middleware.ts",
      "reads": 47,
      "estimatedTokensWasted": 141000,
      "estimatedCostWastedUsd": 0.42,
      "recommendation": "Read 47×. Pin a memory to save ~141K tokens/month."
    }
  ]
}
GET/api/analytics/ingestion

Operational metrics for the hook pipeline — events per minute, dedup rate, error rate, avg processing time. Useful when debugging ingest performance.

Errors

Beta errors return a small JSON body:

example errorjson
{
  "error": "not_found"
}

The error format will become stricter before the public package launch.

Rate limiting

The worker doesn’t rate-limit by default (it’s your machine). Internally it caps to ~10,000 events/sec to keep SQLite happy. If you saturate that, batch with POST /api/hooks/batch.

← PreviousOpenAI Codex CLISession JSONL watcher daemon