Hippocortex API Overview

The Hippocortex REST API provides programmatic access to the memory platform. All SDK operations map directly to API endpoints.

---

Base URL

https://api.hippocortex.dev/v1

For self-hosted deployments, replace with your instance URL.

---

Authentication

Every request must include an authentication header:

Authorization: Bearer <token>

Two token types are supported:

Token Type	Format	Source
API Key	hx_live_*, hx_test_*	Dashboard or API Keys endpoint
JWT	Clerk JWT	Clerk authentication flow

See Authentication for details.

---

Request/Response Format

Request

• Content-Type: application/json
• Accept: application/json
• All request bodies are JSON objects

Response Envelope

Every response follows the same structure:

{
  "ok": true,
  "data": { ... },
  "meta": {
    "requestId": "req-abc123",
    "tenantId": "tenant-xyz",
    "durationMs": 12
  }
}

Error response:

{
  "ok": false,
  "error": {
    "code": "validation_error",
    "message": "type is required and must be a string",
    "details": [
      { "field": "type", "message": "type is required and must be a string" }
    ]
  }
}

---

Rate Limiting

Requests are rate-limited per API key based on the account plan:

Plan	Requests/Minute	Burst Allowance	Monthly Events
Free	60	10	1,000
Developer	600	100	50,000
Pro	3,000	500	500,000
Enterprise	Unlimited	Unlimited	Unlimited

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1709251200

Rate Limit Exceeded

When the limit is exceeded, the API returns HTTP 429:

{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 12 seconds."
  }
}

Include the Retry-After header value in your backoff logic.

---

Error Codes

Code	HTTP Status	Description
validation_error	400	Request body failed validation
unauthorized	401	Missing, expired, or invalid credentials
forbidden	403	Authenticated but insufficient permissions
not_found	404	Requested resource does not exist
conflict	409	Duplicate resource (idempotency)
rate_limited	429	Too many requests
internal_error	500	Server-side error

---

Pagination

List endpoints use cursor-based pagination:

Request:

GET /v1/artifacts?limit=20&cursor=eyJpZCI6ImFydC0wMjAifQ

Response:

{
  "ok": true,
  "data": {
    "artifacts": [...],
    "pagination": {
      "hasMore": true,
      "cursor": "eyJpZCI6ImFydC0wNDAifQ",
      "total": 156
    }
  }
}

• limit: Number of items per page (default: 20, max: 100)
• cursor: Opaque cursor from the previous response
• hasMore: Whether more pages exist
• total: Total item count (when available)

---

Tenant Isolation

All API operations are scoped to the authenticated tenant:

• Tenant ID is extracted from the authentication token (not from request parameters)
• No cross-tenant data access is possible
• Enterprise organizations add an additional scoping layer via X-Organization-ID header

Enterprise Organization Header

For enterprise endpoints, include the organization context:

X-Organization-ID: org-123

This header is required for organization-scoped endpoints (teams, agents, namespaces, policies, audit).

---

Endpoints Summary

Core Endpoints

Method	Endpoint	Description	Auth
POST	/v1/capture	Capture single event	API Key
POST	/v1/capture/batch	Capture batch of events	API Key
POST	/v1/learn	Trigger memory compilation	API Key
POST	/v1/synthesize	Synthesize context	API Key
GET	/v1/artifacts	List artifacts	API Key
GET	/v1/artifacts/:id	Get artifact	API Key
GET	/v1/usage-metrics	Get usage metrics	API Key

Authentication & Account

Method	Endpoint	Description	Auth
POST	/v1/auth/register	Register new account	None
POST	/v1/auth/login	Login	None
GET	/v1/api-keys	List API keys	JWT
POST	/v1/api-keys	Create API key	JWT
DELETE	/v1/api-keys/:id	Revoke API key	JWT

Vault

Method	Endpoint	Description	Auth
POST	/v1/vaults	Create vault	JWT
GET	/v1/vaults	List vaults	JWT
POST	/v1/vaults/:id/items	Create vault item	JWT
GET	/v1/vaults/:id/items	List vault items	JWT
POST	/v1/vaults/:id/items/:itemId/reveal	Reveal secret	JWT
GET	/v1/vaults/:id/audit	Vault audit log	JWT

Enterprise

Method	Endpoint	Description
POST	/v1/organizations	Create organization
GET	/v1/organizations	List organizations
POST	/v1/organizations/:orgId/teams	Create team
POST	/v1/organizations/:orgId/members/invite	Invite member
POST	/v1/organizations/:orgId/agents	Create agent identity
POST	/v1/organizations/:orgId/namespaces	Create namespace
POST	/v1/organizations/:orgId/policies	Create policy
GET	/v1/organizations/:orgId/audit	Query audit logs
GET	/v1/organizations/:orgId/lineage/:memoryId	Get memory lineage
POST	/v1/organizations/:orgId/lifecycle-policies	Create lifecycle policy

See individual endpoint documentation for complete request/response schemas.

---

Health Check

GET /health

Returns system health status (no authentication required):

{
  "status": "healthy",
  "version": "1.0.0",
  "postgres": "connected",
  "redis": "connected",
  "uptime": 86400
}

---

Prometheus Metrics

GET /metrics

Returns Prometheus-format metrics for monitoring (no authentication required in internal network).