API Reference
REST API
Complete documentation for the ekkOS Memory REST API. Use these endpoints to integrate memory into any application.
Base URL
https://mcp.ekkos.devAuthentication
All API requests require a Bearer token in the Authorization header. Get your API key from platform.ekkos.dev.
curl -X POST https://mcp.ekkos.dev/api/v1/memory/search \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{"query": "authentication patterns"}'Rate Limits
| Plan | Requests/Day | Burst Limit |
|---|---|---|
| Free | 100 | 10/min |
| Pro | 10,000 | 100/min |
| Team | Unlimited | 1000/min |
Rate limit headers are included in all responses: X-RateLimit-Remaining, X-RateLimit-Reset
Endpoints
POST
/api/v1/memory/searchSearch memory with semantic query
Parameters
querystringrequiredSemantic search querylimitnumberMax results (default: 10)sourcesstring[]Memory layers to search: patterns, graph, signals, allResponse
{
"retrieval_id": "ret_abc123",
"results": [
{
"id": "mem_xyz",
"content": "Always use Supabase for authentication",
"source": "patterns",
"similarity": 0.92,
"metadata": { "success_rate": 0.85 }
}
],
"timing_ms": 18
}POST
/api/v1/patternsCreate or update a pattern
Parameters
titlestringrequiredPattern titleproblemstringrequiredProblem descriptionsolutionstringrequiredSolution descriptiontagsstring[]Categorization tagsworks_whenstring[]Conditions when pattern appliesanti_patternsstring[]What NOT to doResponse
{
"id": "pat_abc123",
"title": "Use Supabase Auth",
"created_at": "2024-01-15T10:30:00Z",
"confidence": 0.5
}GET
/api/v1/patternsList all patterns
Parameters
limitnumberMax results (default: 50)offsetnumberPagination offsettagsstring[]Filter by tagsResponse
{
"patterns": [
{
"id": "pat_abc123",
"title": "Use Supabase Auth",
"problem": "Need authentication for Next.js app",
"solution": "Use @supabase/auth-helpers-nextjs",
"confidence": 0.85,
"applications": 12,
"success_rate": 0.92
}
],
"total": 62,
"has_more": true
}POST
/api/v1/directivesGet current MUST/NEVER/PREFER/AVOID directives
Parameters
userIdstringUser ID (default: system)windowHoursnumberHours of signals to include (default: 72)Response
{
"directives": [
{
"type": "MUST",
"rule": "Use TypeScript for all new files",
"priority": 800,
"source": "user_preference"
},
{
"type": "NEVER",
"rule": "Use any as a type",
"priority": 700,
"source": "pattern"
}
]
}POST
/api/v1/forgeForge a new insight/pattern from learnings
Parameters
titlestringrequiredClear descriptive titleproblemstringrequiredWhat problem does this solve?solutionstringrequiredThe solution that worksworks_whenstring[]When this pattern appliesanti_patternsstring[]Common mistakes to avoidtagsstring[]Categorization tagsResponse
{
"id": "pat_new123",
"title": "RLS requires service role for admin ops",
"confidence": 0.5,
"message": "Pattern forged successfully"
}POST
/api/v1/workingWrite message to working memory
Parameters
rolestringrequired"user" or "assistant"contentstringrequiredMessage contentsession_idstringrequiredSession identifiersourcestringSource platform (cursor, claude-code, etc)Response
{
"id": "msg_abc123",
"created_at": "2024-01-15T10:30:00Z",
"message": "Message written to working memory"
}POST
/api/v1/reflexValidate AI suggestion against patterns (Hallucination Firewall)
Parameters
requeststringrequiredOriginal user requestproposed_answerstringrequiredAI's proposed responseuser_idstringUser ID for personalized checkingResponse
{
"status": "GROUNDED",
"confidence": 0.89,
"supporting_patterns": [
{ "id": "pat_123", "title": "Use Supabase Auth", "relevance": 0.92 }
],
"conflicts": [],
"explanation": "This suggestion aligns with 3 established patterns"
}Error Codes
| Code | Meaning |
|---|---|
400 | Bad Request — Invalid parameters |
401 | Unauthorized — Invalid or missing API key |
429 | Too Many Requests — Rate limit exceeded |
500 | Internal Error — Something went wrong on our end |
SDKs & Libraries
MCP Server (Node.js)
npm install @ekkos/mcp-server
TypeScript SDK
npm install @ekkos/sdk