REST API

CortexDB exposes a REST API on the HTTP port (default: 8080). All endpoints accept and return JSON.

Authentication

Include your API key in the Authorization header:

curl -H "Authorization: Bearer your-api-key" \
     https://api.cortexdb.io/v1/admin/health

For self-hosted deployments without authentication configured, no header is needed.

Base URL

| Environment | URL | |---|---| | Cloud | https://api.cortexdb.io | | Self-hosted | http://localhost:8080 (default) | | Docker | http://localhost:8080 |

Endpoints Overview

| Method | Path | Description | |---|---|---| | POST | /v1/remember | Store an episode | | POST | /v1/recall | Retrieve relevant memories | | POST | /v1/forget | Remove memories from results | | POST | /v1/search | Lower-level search | | POST | /v1/episodes | Batch ingest episodes | | GET | /v1/episodes/:id | Get a specific episode | | GET | /v1/entities | List entities | | GET | /v1/entities/:id | Get entity with relationships | | POST | /v1/link | Create entity relationship | | GET | /v1/admin/health | Health check | | GET | /v1/admin/metrics | Prometheus metrics |

Remember

curl -X POST https://api.cortexdb.io/v1/remember \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "my-app",
    "episode": {
      "type": "message",
      "content": "We decided to use gRPC for internal services.",
      "source": "slack",
      "author": "alice",
      "timestamp": "2026-03-15T10:00:00Z"
    }
  }'

Response (201):

{
  "event_id": 42,
  "episode_id": "ep_abc123",
  "timestamp": "2026-03-15T10:00:01Z"
}

Recall

curl -X POST https://api.cortexdb.io/v1/recall \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "my-app",
    "query": "What protocol are we using?",
    "top_k": 5,
    "filters": {
      "episode_type": "decision"
    }
  }'

Response (200):

{
  "memories": [
    {
      "id": "ep_abc123",
      "content": "We decided to use gRPC for internal services.",
      "score": 0.94,
      "episode_type": "decision",
      "source": "slack",
      "author": "alice",
      "timestamp": "2026-03-15T10:00:00Z",
      "entities": [
        {"name": "gRPC", "type": "technology"},
        {"name": "alice", "type": "person"}
      ],
      "metadata": {}
    }
  ],
  "query_entities": ["gRPC", "protocol"],
  "total_candidates": 12,
  "latency_ms": 87.3
}

Forget

curl -X POST https://api.cortexdb.io/v1/forget \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "my-app",
    "memory_id": "ep_abc123"
  }'

Response (200):

{
  "count": 1,
  "event_ids": [43]
}

Search

curl -X POST https://api.cortexdb.io/v1/search \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "my-app",
    "query": "authentication middleware",
    "mode": "hybrid",
    "top_k": 10
  }'

Response (200):

{
  "hits": [
    {
      "id": "ep_def456",
      "content": "Refactored auth middleware to support JWT and API keys.",
      "score": 0.87,
      "episode_type": "code",
      "source": "github",
      "metadata": {"repo": "acme/backend", "pr": 234}
    }
  ],
  "total": 1,
  "latency_ms": 34.2
}

Batch Ingest Episodes

curl -X POST https://api.cortexdb.io/v1/episodes \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "my-app",
    "episodes": [
      {"type": "message", "content": "First episode.", "source": "test"},
      {"type": "message", "content": "Second episode.", "source": "test"}
    ]
  }'

Response (201):

{
  "count": 2,
  "event_ids": [44, 45],
  "errors": []
}

Get Episode

curl https://api.cortexdb.io/v1/episodes/ep_abc123 \
  -H "Authorization: Bearer your-api-key" \
  -G -d "tenant_id=my-app"

List Entities

curl https://api.cortexdb.io/v1/entities \
  -H "Authorization: Bearer your-api-key" \
  -G -d "tenant_id=my-app" -d "type=technology" -d "limit=20"

Get Entity

curl https://api.cortexdb.io/v1/entities/ent_xyz789 \
  -H "Authorization: Bearer your-api-key" \
  -G -d "tenant_id=my-app"

Response (200):

{
  "id": "ent_xyz789",
  "name": "gRPC",
  "type": "technology",
  "mention_count": 14,
  "first_seen": "2026-02-01T00:00:00Z",
  "last_seen": "2026-03-15T10:00:00Z",
  "relationships": [
    {
      "type": "used_by",
      "target": {"id": "ent_svc001", "name": "payments service", "type": "service"},
      "confidence": 0.95,
      "evidence_count": 3
    }
  ]
}

Link

curl -X POST https://api.cortexdb.io/v1/link \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "my-app",
    "source_entity": "ent_123",
    "target_entity": "ent_456",
    "relationship": "depends_on"
  }'

Health Check

curl https://api.cortexdb.io/v1/admin/health

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "validation_error",
    "message": "Field 'tenant_id' is required.",
    "request_id": "req_abc123"
  }
}

| Status Code | Error Code | Description | |---|---|---| | 400 | validation_error | Invalid request parameters | | 401 | authentication_error | Missing or invalid API key | | 403 | authorization_error | Insufficient permissions | | 404 | not_found | Resource not found | | 429 | rate_limit | Too many requests (includes Retry-After header) | | 500 | internal_error | Server error |

Next Steps