REST API

CortexDB exposes a REST API on the HTTP port (default: 3141). 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.ai/v1/admin/health

Base URL

| Environment | URL | |---|---| | Cloud | https://api.cortexdb.ai | | Local | http://localhost:3141 |

Endpoints Overview

| Method | Path | Description | |---|---|---| | POST | /v1/remember | Store a memory | | POST | /v1/recall | Retrieve relevant memories | | POST | /v1/forget | Remove memories | | POST | /v1/search | Search with filters | | POST | /v1/episodes | Ingest a structured episode | | GET | /v1/episodes | List episodes | | 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 | Server metrics |

Remember

Store a piece of information in CortexDB.

curl -X POST https://api.cortexdb.ai/v1/remember \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "We decided to use gRPC for internal services.",
    "tenant_id": "my-app"
  }'

Response (201):

{
  "event_id": "019d6359-d3cc-7671-9e4c-9151011fa016"
}

Optional fields

| Field | Type | Description | |---|---|---| | content | string | Required. The text to remember. | | tenant_id | string | Tenant namespace (default: "default"). | | scope | string | Optional scope qualifier. | | metadata | object | Arbitrary key-value metadata. |

Recall

Retrieve relevant memories matching a natural-language query.

curl -X POST https://api.cortexdb.ai/v1/recall \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What protocol are we using for internal services?",
    "tenant_id": "my-app"
  }'

Response (200):

{
  "context": "We decided to use gRPC for internal services.",
  "confidence": 0.95,
  "latency_ms": 42
}

Fields

| Field | Type | Description | |---|---|---| | query | string | Required. Natural-language query. | | tenant_id | string | Tenant namespace (default: "default"). |

Forget

Delete memories matching a query.

curl -X POST https://api.cortexdb.ai/v1/forget \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "gRPC decision",
    "reason": "Decision reversed",
    "tenant_id": "my-app"
  }'

Response (200):

{
  "forgotten_entities": 1,
  "forgotten_edges": 0,
  "audit_id": "019d6359-f063-7771-a315-d0d499ecf871"
}

Fields

| Field | Type | Description | |---|---|---| | query | string | Pattern or identifier of memories to delete. | | reason | string | Required. Justification for the deletion. | | tenant_id | string | Tenant namespace (default: "default"). |

Search

Search across memories and episodes with optional filters.

curl -X POST https://api.cortexdb.ai/v1/search \
  -H "Authorization: Bearer your-api-key" \
  -H "x-tenant-id: my-app" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "authentication middleware",
    "limit": 10
  }'

With filters:

curl -X POST https://api.cortexdb.ai/v1/search \
  -H "Authorization: Bearer your-api-key" \
  -H "x-tenant-id: my-app" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "deploy failure",
    "limit": 10,
    "filters": {
      "source": "github",
      "time_range": "7d"
    }
  }'

Response (200):

{
  "context": "Refactored auth middleware to support JWT and API keys.",
  "confidence": 0.9,
  "latency_ms": 35,
  "episodes": [],
  "total_episodes": 0
}

Fields

| Field | Type | Description | |---|---|---| | query | string | Required. Natural-language search query. | | limit | integer | Max results (default: 20). | | offset | integer | Pagination offset (default: 0). | | filters.source | string | Filter by source connector (e.g., "slack", "github"). | | filters.episode_type | string | Filter by episode type. | | filters.time_range | string | Time range (e.g., "1h", "24h", "7d", "30d"). | | filters.namespace | string | Filter by namespace. |

Note: tenant_id is passed via the x-tenant-id header for search.

Ingest Episode

Ingest a structured episode with full metadata.

curl -X POST https://api.cortexdb.ai/v1/episodes \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Deploy v2.1 to production completed.",
    "tenant_id": "my-app",
    "episode_type": "deployment",
    "actor": {
      "id": "ci-bot",
      "name": "CI Bot",
      "actor_type": "service"
    },
    "source": {
      "connector": "github",
      "external_id": "deploy-123"
    },
    "metadata": {
      "commit": "abc123",
      "branch": "main"
    }
  }'

Response (201):

{
  "episode_id": "019d6359-d3cc-7671-9e4c-9151011fa016",
  "event_id": "019d6359-d3cc-7671-9e4c-9151011fa017",
  "ingested_at": "2026-03-15T10:00:01Z"
}

List Episodes

curl https://api.cortexdb.ai/v1/episodes?tenant_id=my-app&limit=10 \
  -H "Authorization: Bearer your-api-key"

Response (200):

{
  "episodes": [],
  "total": 0,
  "has_more": false
}

List Entities

curl https://api.cortexdb.ai/v1/entities \
  -H "Authorization: Bearer your-api-key" \
  -H "x-tenant-id: my-app"

Response (200):

{
  "entities": [],
  "total": 0
}

Get Entity

curl https://api.cortexdb.ai/v1/entities/payments-service \
  -H "Authorization: Bearer your-api-key" \
  -H "x-tenant-id: my-app"

Response (200):

{
  "id": "payments-service",
  "name": "payments service",
  "entity_type": "service",
  "first_seen": "2026-02-01T00:00:00Z",
  "last_seen": "2026-03-15T10:00:00Z",
  "episode_count": 14,
  "relationships": [
    {
      "id": "edge-001",
      "source_entity_id": "payments-service",
      "target_entity_id": "auth-service",
      "relationship": "DEPENDS_ON",
      "fact": "Payments calls auth for token validation",
      "confidence": 0.95,
      "created_at": "2026-03-15T10:00:00Z"
    }
  ],
  "recent_episodes": []
}

Link

Create an explicit relationship between two entities.

curl -X POST https://api.cortexdb.ai/v1/link \
  -H "Authorization: Bearer your-api-key" \
  -H "x-tenant-id: my-app" \
  -H "Content-Type: application/json" \
  -d '{
    "source_entity_id": "payments-service",
    "target_entity_id": "auth-service",
    "relationship": "DEPENDS_ON",
    "fact": "Payments calls auth for token validation",
    "confidence": 0.95
  }'

Response (200):

{
  "id": "edge-001",
  "created_at": "2026-03-15T10:00:00Z"
}

Health Check

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

Response (200):

{
  "status": "healthy",
  "storage": "ok",
  "version": "0.1.0"
}

Metrics

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

Response (200):

{
  "requests_total": 1042,
  "requests_active": 0,
  "errors_total": 3,
  "rate_limited_total": 0
}

Error Responses

All errors follow a consistent format:

{
  "error": "not_found",
  "message": "entity payments-service not found"
}

| Status Code | Error Code | Description | |---|---|---| | 400 | validation_error | Invalid request parameters | | 401 | authentication_error | Missing or invalid API key | | 402 | connector_not_available | Feature requires a higher tier | | 403 | authorization_error | Insufficient permissions | | 404 | not_found | Resource not found | | 422 | deserialization_error | Invalid JSON body | | 429 | rate_limit | Too many requests (includes Retry-After header) | | 500 | internal_error | Server error |

Next Steps