Skip to content

HTTP API

The HTTP API is the unified backend that powers the CLI, MCP server, and SDKs. It provides RESTful endpoints for all memory operations, search, connectors, governance, and system management.

Base URL

http://localhost:8787

The default port is 8787. Override with COGNIBRAIN_PORT or --port on cognibrain start.

Authentication

curl -H "X-API-Key: your-key" http://localhost:8787/api/memories

curl -H "Authorization: Bearer your-jwt" http://localhost:8787/api/memories

curl http://localhost:8787/api/memories

Note

Local solo-dev profile doesn't require authentication. Production deployments should always configure auth.

OpenAPI Specification

The full OpenAPI spec is available at runtime:

curl http://localhost:8787/openapi.json

Use this for generating clients, testing with Swagger UI, or integration validation.

Core Endpoints

Memories

List Memories

GET /api/memories

Query parameters:

Param Type Description
scope string Filter by scope (repo, user, global, task)
status string Filter by status (active, stale, review)
limit number Max results (default: 50)
offset number Pagination offset

Response:

{
  "memories": [
    {
      "id": "mem_abc123",
      "content": "Always run npm test before release",
      "scope": "repo",
      "status": "active",
      "createdAt": "2026-06-01T10:00:00Z",
      "lastRecalledAt": "2026-06-10T14:30:00Z"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Create Memory

POST /api/memories

Request body:

{
  "content": "This repo uses npm test before release",
  "scope": "repo"
}

Response:

{
  "id": "mem_abc123",
  "content": "This repo uses npm test before release",
  "scope": "repo",
  "status": "active",
  "createdAt": "2026-06-11T12:00:00Z"
}

Get Memory

GET /api/memories/:id

Update Memory

PATCH /api/memories/:id

Archive Memory

DELETE /api/memories/:id

Context & Retrieval

Get Context Pack

POST /api/context

Request body:

{
  "task": "prepare the release patch",
  "repo": "cognilabz/cognibrain",
  "tokenBudget": 1200
}

Response:

{
  "context": "Relevant memories for this task...",
  "memoriesUsed": 5,
  "tokenCount": 890
}

Get Coding Context

POST /api/coding-context

Request body:

{
  "task": "fix auth refresh",
  "files": ["src/auth.ts"]
}

Action Guards

Check Guard

POST /api/guard

Request body:

{
  "action": "edit src/api/server.ts"
}

Response:

{
  "allowed": true,
  "warnings": [],
  "blockers": []
}

Evidence

Record Outcome

POST /api/outcome

Request body:

{
  "command": "npm test",
  "exitCode": 0
}

Record Patch Evidence

POST /api/patch-evidence

Request body:

{
  "task": "release patch",
  "files": ["package.json"],
  "commands": ["npm test"]
}

Response:

{
  "evidenceId": "ev_xyz789",
  "task": "release patch",
  "files": ["package.json"],
  "commands": ["npm test"],
  "memoriesUsed": ["mem_abc123"]
}

Get Evidence Pack

POST /api/evidence-pack

Connectors

List Connectors

GET /api/connectors

Add Connector

POST /api/connectors

Connector Health

GET /api/connectors/:id/health

System

Health Check

GET /api/health

Response:

{
  "status": "healthy",
  "memoryCount": 42,
  "uptime": 86400,
  "version": "0.1.0"
}

Dream Cycle

POST /api/dream-cycle

Conflicts

GET /api/conflicts

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "MEMORY_NOT_FOUND",
    "message": "Memory with ID mem_xyz does not exist",
    "status": 404
  }
}

Common error codes:

Code HTTP Status Description
UNAUTHORIZED 401 Missing or invalid credentials
FORBIDDEN 403 Insufficient permissions
MEMORY_NOT_FOUND 404 Memory ID doesn't exist
VALIDATION_ERROR 422 Invalid request body
RATE_LIMITED 429 Too many requests
INTERNAL_ERROR 500 Server error

Rate Limiting

Default rate limits for the local daemon:

Endpoint Limit
Read operations 1000/min
Write operations 100/min
Context/search 200/min

Production deployments can configure custom limits via environment variables.