API Reference

Complete REST API documentation for Hippocortex. All endpoints require authentication and return JSON responses.

Base URL

https://api.hippocortex.dev/v1

Authentication

All API requests require a Bearer token in the Authorization header. Use your API key directly as the Bearer token.

Authorization Header

Authorization: Bearer hx_live_abc123...

API Key Formats

hx_live_*Production keys. Use for live applications. Events are persisted and processed.

hx_test_*Test keys. Use for development and testing. Events are processed but may have separate quotas.

API keys support scoped permissions (read, write, admin) configured at creation time. Keys are hashed server-side and cannot be retrieved after initial generation. Rotation is supported without downtime by creating a new key before revoking the old one.

Response Format

All responses follow a consistent envelope format. Successful responses have ok: true with data in the data field. Error responses have ok: false with error details. Every response includes a meta object with request tracking information.

Success Response

{
  "ok": true,
  "data": { ... },
  "meta": {
    "requestId": "req_abc123",
    "tenantId": "ten_xyz789",
    "durationMs": 42
  }
}

Error Response

{
  "ok": false,
  "error": {
    "code": "validation_error",
    "message": "type is required and must be a string",
    "details": [
      { "field": "type" }
    ]
  },
  "meta": {
    "requestId": "req_abc123",
    "tenantId": "ten_xyz789",
    "durationMs": 5
  }
}

Rate Limiting

API requests are rate-limited per API key and per tenant. When you exceed the rate limit, the API responds with HTTP 429 and a Retry-After header indicating how many seconds to wait before retrying.

Free tier60 requests per minute per key

Developer tier300 requests per minute per key

Pro tier1,000 requests per minute per key

EnterpriseCustom limits, configurable per key

Idempotency

The POST /v1/capture and POST /v1/capture/batch endpoints support idempotency keys. Include an idempotencyKey field in your event payload to prevent duplicate processing. If a request with the same idempotency key has already been processed, the API returns the original result without re-processing.

Endpoints

POST/v1/capture

Capture a single agent event. The event is validated and queued for asynchronous processing via Redis/BullMQ workers. Returns immediately with a 202 status and a job reference.

Request Headers

Authorization: Bearer hx_live_...
Content-Type: application/json

Request Body

application/json

{
  "type": "message",
  "sessionId": "sess-001",
  "payload": {
    "role": "user",
    "content": "Deploy the payment service"
  },
  "metadata": {
    "agentId": "deploy-bot",
    "source": "api"
  },
  "idempotencyKey": "idem-abc123"
}

typerequiredEvent type: message, tool_call, tool_result, file_edit, test_run, command_exec, browser_action, api_result

sessionIdrequiredSession identifier grouping related events

payloadrequiredEvent-specific data object

metadataoptionalArbitrary metadata (agentId, source, etc.)

idempotencyKeyoptionalUnique key for deduplication

Response

202 Accepted

{
  "ok": true,
  "data": {
    "jobId": "job_abc123",
    "status": "queued",
    "idempotencyKey": "idem-abc123"
  },
  "meta": {
    "requestId": "req_xyz",
    "tenantId": "ten_123",
    "durationMs": 12
  }
}

Status Codes

202Event accepted and queued for processing.

401Invalid or missing API key.

422Invalid request body or missing required fields.

429Rate limit exceeded.

curl Example

curl

curl -X POST https://api.hippocortex.dev/v1/capture \
  -H "Authorization: Bearer hx_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "message",
    "sessionId": "sess-001",
    "payload": {"role": "user", "content": "Deploy to staging"}
  }'

POST/v1/capture/batch

Capture multiple events in a single request. Maximum batch size is 1,000 events. Events are validated individually. Valid events are queued even if some fail validation. Returns a 202 with a batch summary.

Request Body

application/json

{
  "events": [
    {
      "type": "message",
      "sessionId": "sess-001",
      "payload": {"role": "user", "content": "Hello"}
    },
    {
      "type": "tool_call",
      "sessionId": "sess-001",
      "payload": {"tool_name": "search", "input": "query string"}
    }
  ]
}

Response

202 Accepted

{
  "ok": true,
  "data": {
    "batchId": "batch_xyz",
    "queued": 2,
    "errors": 0,
    "total": 2
  },
  "meta": {
    "requestId": "req_xyz",
    "tenantId": "ten_123",
    "durationMs": 28
  }
}

Status Codes

202Batch accepted. Check response for per-event errors.

401Invalid or missing API key.

422events field missing or not an array, or batch exceeds 1,000 events.

429Rate limit exceeded.

curl Example

curl

curl -X POST https://api.hippocortex.dev/v1/capture/batch \
  -H "Authorization: Bearer hx_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"type": "message", "sessionId": "s1", "payload": {"role": "user", "content": "Hi"}},
      {"type": "message", "sessionId": "s1", "payload": {"role": "assistant", "content": "Hello!"}}
    ]
  }'

POST/v1/synthesize

Synthesize compressed context from semantic memories and compiled artifacts. This is a synchronous endpoint that returns results immediately. The response contains context entries packed within the specified token budget, prioritized by relevance to the query.

Request Body

application/json

{
  "query": "deploy payment service",
  "agentId": "ops-agent",
  "maxTokens": 4000,
  "includeArtifacts": true,
  "includeMemories": true,
  "tags": ["deployment", "payments"]
}

queryoptionalSemantic search query. If omitted, returns the most recent memories and artifacts.

agentIdoptionalFilter to a specific agent's memory.

maxTokensoptionalToken budget for the response. Defaults to 4000.

includeArtifactsoptionalInclude compiled artifacts. Defaults to true.

includeMemoriesoptionalInclude raw semantic memories. Defaults to true.

tagsoptionalFilter memories by tags (array of strings).

Response

200 OK

{
  "ok": true,
  "data": {
    "sections": [
      {
        "type": "memory",
        "content": "Payment service deployment requires staging validation...",
        "source": "mem_abc123",
        "confidence": 0.87
      },
      {
        "type": "artifact",
        "content": "Task schema: deploy-payment-service...",
        "source": "art_xyz789"
      }
    ],
    "totalTokens": 1842,
    "query": "deploy payment service",
    "contextPack": {
      "entries": 5,
      "estimatedTokens": 1842,
      "maxTokens": 4000
    }
  },
  "meta": {
    "requestId": "req_xyz",
    "tenantId": "ten_123",
    "durationMs": 156
  }
}

Status Codes

200Context synthesized successfully.

401Invalid or missing API key.

429Rate limit exceeded.

curl Example

curl

curl -X POST https://api.hippocortex.dev/v1/synthesize \
  -H "Authorization: Bearer hx_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"query": "deploy payment service", "maxTokens": 4000}'

POST/v1/learn

Trigger an asynchronous compilation job that processes captured events into semantic memories and compiled knowledge artifacts. The job runs in the background via BullMQ workers. Returns immediately with a 202 and a job reference.

Request Body

application/json

{
  "agentId": "ops-agent",
  "sessionId": "sess-001",
  "eventIds": ["evt_1", "evt_2"],
  "options": {
    "maxEvents": 500,
    "artifactType": "task_schema"
  }
}

agentIdoptionalScope compilation to a specific agent.

sessionIdoptionalScope compilation to a specific session.

eventIdsoptionalCompile only specific events by ID.

options.maxEventsoptionalMaximum number of events to process in this run.

options.artifactTypeoptionalRestrict output to a specific artifact type.

All fields are optional. An empty request body processes all unprocessed events for the tenant.

Response

202 Accepted

{
  "ok": true,
  "data": {
    "jobId": "job_learn_abc123",
    "status": "queued"
  },
  "meta": {
    "requestId": "req_xyz",
    "tenantId": "ten_123",
    "durationMs": 8
  }
}

Status Codes

202Compilation job queued successfully.

401Invalid or missing API key.

429Rate limit exceeded.

curl Example

curl

curl -X POST https://api.hippocortex.dev/v1/learn \
  -H "Authorization: Bearer hx_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{}'

GET/v1/artifacts

List compiled knowledge artifacts for the authenticated tenant. Supports filtering by type, offset-based pagination, and a configurable page size (max 100).

Query Parameters

typeoptionalFilter by artifact type: task_schema, failure_playbook, causal_pattern, decision_policy

limitoptionalPage size (1 to 100). Defaults to 50.

offsetoptionalNumber of items to skip. Defaults to 0.

Response

200 OK

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "art_abc123",
        "type": "task_schema",
        "title": "Payment Service Deployment",
        "version": 3,
        "tokenCount": 450,
        "isActive": true,
        "compiledAt": "2026-03-14T10:30:00Z",
        "createdAt": "2026-03-10T08:00:00Z"
      }
    ],
    "total": 42,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  },
  "meta": {
    "requestId": "req_xyz",
    "tenantId": "ten_123",
    "durationMs": 35
  }
}

Status Codes

200Artifacts listed successfully.

401Invalid or missing API key.

curl Example

curl

curl https://api.hippocortex.dev/v1/artifacts?type=task_schema&limit=10 \
  -H "Authorization: Bearer hx_live_abc123"

GET/v1/artifacts/:id

Retrieve a single compiled artifact by its ID. Returns the full artifact including content, source references, and metadata.

Path Parameters

idrequiredThe artifact ID (e.g. art_abc123)

Response

200 OK

{
  "ok": true,
  "data": {
    "id": "art_abc123",
    "type": "task_schema",
    "title": "Payment Service Deployment",
    "content": { "steps": [...], "preconditions": [...] },
    "version": 3,
    "tokenCount": 450,
    "sourceEvents": ["evt_1", "evt_2", "evt_3"],
    "sourceMemories": ["mem_1", "mem_2"],
    "metadata": { "compiledBy": "compiler-v2" },
    "isActive": true,
    "compiledAt": "2026-03-14T10:30:00Z",
    "createdAt": "2026-03-10T08:00:00Z",
    "updatedAt": "2026-03-14T10:30:00Z"
  },
  "meta": {
    "requestId": "req_xyz",
    "tenantId": "ten_123",
    "durationMs": 18
  }
}

Status Codes

200Artifact retrieved successfully.

401Invalid or missing API key.

404Artifact not found.

curl Example

curl

curl https://api.hippocortex.dev/v1/artifacts/art_abc123 \
  -H "Authorization: Bearer hx_live_abc123"

GET/v1/usage-metrics

Retrieve usage statistics and quota information for the authenticated tenant. Includes event counts, compilation activity, synthesis usage, and remaining quota.

Response

200 OK

{
  "ok": true,
  "data": {
    "plan": "developer",
    "period": {
      "month": "2026-03",
      "day": "2026-03-14"
    },
    "usage": {
      "eventsThisMonth": 12450,
      "synthesesToday": 84,
      "compilationsToday": 3,
      "requestsThisMinute": 12
    },
    "totals": {
      "events": 45230,
      "memories": 8120,
      "artifacts": 156
    }
  },
  "meta": {
    "requestId": "req_xyz",
    "tenantId": "ten_123",
    "durationMs": 45
  }
}

Status Codes

200Metrics retrieved successfully.

401Invalid or missing API key.

curl Example

curl

curl https://api.hippocortex.dev/v1/usage-metrics \
  -H "Authorization: Bearer hx_live_abc123"

GET/v1/health

System health check endpoint. Returns the status of all subsystems including PostgreSQL, Redis, worker queues, and active alerts. Does not require authentication.

Response

200 OK

{
  "ok": true,
  "data": {
    "status": "healthy",
    "version": "1.1.0",
    "uptime": 86400,
    "timestamp": "2026-03-14T10:00:00Z",
    "subsystems": {
      "postgres": {
        "status": "healthy",
        "connections": {
          "total": 5,
          "idle": 3,
          "waiting": 0,
          "max": 20,
          "utilizationPercent": 25
        }
      },
      "redis": {
        "status": "healthy",
        "latencyMs": 1,
        "persistence": {
          "aof_enabled": true,
          "rdb_last_save_time": 1710410400
        },
        "memory": {
          "used_memory_mb": 128,
          "maxmemory_mb": 512,
          "maxmemory_policy": "noeviction"
        }
      },
      "workers": {
        "status": "healthy",
        "queues": {
          "capture": { "waiting": 0, "active": 2, "failed": 0 },
          "learn": { "waiting": 0, "active": 0, "failed": 0 }
        },
        "totalBacklog": 0
      }
    },
    "alerts": {
      "firing": 0
    }
  }
}

Status Codes

200All systems healthy.

503One or more subsystems are degraded or unhealthy.

curl Example

curl

curl https://api.hippocortex.dev/v1/health