The identity developer API
Programmatic access to memories, segments, and context generation. Treat this like a Stripe-style REST API — JSON in, JSON out, bearer auth, cursors for pagination, and versioned under /v1.
Overview
Every request is authenticated with a bearer token from POST /v1/auth/token. All responses return application/json; charset=utf-8. Mutations are idempotent when you pass an Idempotency-Key header.
The core objects are memories (individual facts Cortext has learned about you), segments (grouped contexts like work, personal, research), and contexts (compiled prompts ready to inject into a model provider).
Exchange token
/v1/auth/tokenExchange a personal access token (PAT) or OAuth authorization code for a short-lived session token. Session tokens are valid for 60 minutes and carry only the scopes granted at exchange time.
Request body
"color:var(--accent-cyan)">curl "color:var(--accent-cyan)">-X POST https://api.cortext.ai/v1/auth/token \ "color:var(--accent-cyan)">-H "color:#86efac">'Content-Type: application/json' \ "color:var(--accent-cyan)">--data "color:#86efac">'{ "grant_type": "personal_access_token", "pat": "ctx_pat_sk_live_abc123" }'
Response · 200 OK
{
"access_token": "ctx_sess_2LHLW5S9xNLRKrnvRbTT",
"token_type": "bearer",
"expires_in": 3600,
"refresh_token": "ctx_ref_a7f2c81d",
"scope": "read:memories write:memories read:segments write:context",
"subject": {
"user_id": "usr_01HN3P7R8QZ",
"email": "jaivien@cortext.ai"
}
}Refresh session
/v1/auth/refreshSwap a refresh_token for a new short-lived access token. Does not rotate scopes. Refresh tokens are single-use and rotate on every refresh.
Request body
Response · 200 OK
{
"access_token": "ctx_sess_9P2RN4X7JKL8MQF3",
"token_type": "bearer",
"expires_in": 3600,
"refresh_token": "ctx_ref_b9e41d77"
}List memories
/v1/memoriesPaginated list of memories attached to the authenticated user. Supports filtering by segment, confidence score, and free-text search.
Path & query parameters
Response · 200 OK
{
"data": [
{
"id": "mem_01HN4A3B7CX",
"body": "Prefers concise answers over long-form explanations.",
"segment_id": "seg_work",
"confidence": 0.92,
"source": "auto",
"created_at": "2026-03-11T14:22:18Z",
"last_reinforced_at": "2026-04-14T09:15:02Z"
},
{
"id": "mem_01HN4A3B7CY",
"body": "Allergic to cilantro.",
"segment_id": "seg_personal",
"confidence": 1.00,
"source": "user",
"created_at": "2026-02-02T19:40:01Z",
"last_reinforced_at": "2026-02-02T19:40:01Z"
}
],
"next_cursor": "eyJpZCI6Im1lbV8wMUhON..."
}Create memory
/v1/memoriesAdd a new memory explicitly. Cortext also generates memories automatically from synced conversations — this endpoint is for user-asserted facts that should be treated as authoritative.
Request body
"color:var(--accent-cyan)">curl "color:var(--accent-cyan)">-X POST https://api.cortext.ai/v1/memories \ "color:var(--accent-cyan)">-H "color:#86efac">'Authorization: Bearer ctx_sess_...' \ "color:var(--accent-cyan)">-H "color:#86efac">'Idempotency-Key: 9b74c5a3-4d1e-4b1d-a7d1-0a30fb8a' \ "color:var(--accent-cyan)">--data "color:#86efac">'{ "body": "Uses Linear for project tracking.", "segment_id": "seg_work" }'
Response · 200 OK
{
"id": "mem_01HNK9P2X7Q",
"body": "Uses Linear for project tracking.",
"segment_id": "seg_work",
"confidence": 1.00,
"source": "user",
"created_at": "2026-04-18T19:02:44Z"
}Update memory
/v1/memories/:idPatch any subset of a memory's mutable fields. Changes the last_reinforced_at timestamp and resets the confidence decay curve.
Request body
Response · 200 OK
{
"id": "mem_01HNK9P2X7Q",
"body": "Uses Linear (and occasionally Height) for project tracking.",
"segment_id": "seg_work",
"confidence": 0.98,
"updated_at": "2026-04-18T19:08:01Z"
}Delete memory
/v1/memories/:idPermanently deletes a memory. Deletes cascade through any active context snapshots within 10 seconds.
Response · 200 OK
{
"id": "mem_01HNK9P2X7Q",
"deleted": true,
"deleted_at": "2026-04-18T19:14:23Z"
}List segments
/v1/segmentsEvery user has one or more segments. Each segment is a named bundle of memories — think of them as personas or contexts.
Response · 200 OK
{
"data": [
{ "id": "seg_personal", "name": "Personal", "memory_count": 143, "is_default": true, "active": true },
{ "id": "seg_work", "name": "Work", "memory_count": 287, "is_default": false, "active": true },
{ "id": "seg_research", "name": "Research", "memory_count": 92, "is_default": false, "active": false }
]
}Activate segment
/v1/segments/:id/activateActivating a segment causes subsequent calls to /v1/context/generate to pull memories from it. Multiple segments can be active simultaneously; Cortext blends them and deduplicates overlapping facts.
Request body
Response · 200 OK
{
"id": "seg_work",
"active": true,
"activated_at": "2026-04-18T19:20:11Z",
"memories_in_context": 287
}Generate context
/v1/context/generateCompiles active memories into a model-ready context string. Cortext handles provider-specific formatting — OpenAI chat messages, Anthropic system prompts, Gemini system_instructions.
Request body
"color:var(--accent-cyan)">curl "color:var(--accent-cyan)">-X POST https://api.cortext.ai/v1/context/generate \ "color:var(--accent-cyan)">-H "color:#86efac">'Authorization: Bearer ctx_sess_...' \ "color:var(--accent-cyan)">--data "color:#86efac">'{ "target": "anthropic", "max_tokens": 1200 }'
Response · 200 OK
{
"context_id": "ctx_01HNKA7ZPXQ",
"target": "anthropic",
"format": "system_prompt",
"token_estimate": 1174,
"memories_used": 82,
"memories_available": 287,
"salience_cutoff": 0.41,
"payload": "You are speaking with Jaivien Kendrick. Facts you should know: ...",
"expires_at": "2026-04-18T19:50:11Z"
}Inject into conversation
/v1/context/injectForwards a compiled context to a downstream provider alongside the user's first message. Useful for tools that want to delegate provider-selection and key management to Cortext.
Request body
Response · 200 OK
{
"provider": "anthropic",
"model": "claude-sonnet-4-5",
"request_id": "req_01HNKAJ2V8B",
"response": {
"id": "msg_01A7B9",
"role": "assistant",
"content": "Got it — locking in the Thursday demo ..."
},
"usage": { "input_tokens": 2341, "output_tokens": 214 }
}Error shapes
Errors use the application/problem+json content type and follow RFC 7807. Every response carries a stable type URI you can pattern-match against, a human-readable title, and a request-scoped trace_id.
{
"type": "https://cortext.ai/errors/memory-too-long",
"title": "Memory body exceeds 500 characters",
"status": 422,
"detail": "Memory bodies are limited to 500 characters. Received 812.",
"trace_id": "trc_01HNKB9QF2V",
"field": "body"
}Status codes
Rate limits
The default budget is 600 requests per minute per access token, burstable to 1000. Context generation is metered separately at 60 per minute because it's compute-heavy. Every response returns the current window state:
X-RateLimit-Limit: 600 X-RateLimit-Remaining: 584 X-RateLimit-Reset: 1713474421 Retry-After: 7
If you hit the limit you'll get a 429 with a Retry-After header (in seconds). We recommend exponential backoff with jitter starting at the advertised value.