API Reference
TL;DR cachly AI Brain — persistent memory and managed cache for AI coding assistants and autonomous agents. Give Claude Code, Cursor, Windsurf, GitHub Copilot, and any MCP-compatible editor a Brain that remembers lessons, sessions, and code across every session, every machine, and…
Full spec: /openapi.yaml (OpenAPI 3.1). Production server: https://api.cachly.dev.
Authentication#
Scheme
Use
BearerAuth API key or Keycloak JWT in an Authorization: Bearer <token> header
AdminAuth Static bearer token (ADMIN_SECRET_KEY)
VectorToken Per-instance UUID in the URL path: /v1/sem/{token}/...
OAuth2 client_credentials Headless machine-to-machine auth for CI runners, agents, and AI-to-AI pipelines. Set CACHLY_CLIENT_ID + CACHLY_CLIENT_SECRET; the MCP server exchanges them for an access token against Keycloak — no device flow, no human
Machine-to-machine (gRPC): beyond the REST surface, a gRPC BrainService (Search / Recall / Learn / Subscribe / Health) is available on port 50051 for low-latency AI-to-AI access — including a write path (Learn) so agents and CI runners can teach the Brain directly, and a streaming read-push path (Subscribe) that delivers lessons to agents the moment they're learned. Per-token rate limiting, optional TLS, and request-ID correlation apply to unary and streaming RPCs alike. Reflection is enabled for grpcurl and grpc-health-probe.
The MCP tool surface (137 tools) is also exportable to OpenAI / Anthropic / LangChain / OpenAPI dialects:
npx @cachly-dev/mcp-server@latest tool-specs --format= < dialect > Quick start: npx @cachly-dev/mcp-server@latest autopilot — one command detects all editors, writes configs, and bootstraps your Brain. No credit card.
Endpoints by resource group#
Health#
Method
Path
Description
GET
/healthAPI health check
Instances (Keycloak JWT required)#
Method
Path
Description
POST
/api/v1/instancesCreate cache instance
GET
/api/v1/instancesList instances
GET
/api/v1/instances/{id}Get instance
DELETE
/api/v1/instances/{id}Delete instance
POST
/api/v1/instances/{id}/rotate-vector-tokenRotate vector token
POST
/api/v1/instances/{id}/warmWarm cache
PUT / DELETE
/api/v1/instances/{id}/byokSet / remove BYOK key
PUT
/api/v1/instances/{id}/cost-per-callSet cost per call for ROI estimates
PUT / DELETE
/api/v1/instances/{id}/custom-domainSet / remove custom domain
POST
/api/v1/instances/{id}/custom-domain/verifyVerify custom domain
PUT / DELETE
/api/v1/instances/{id}/webhookSet / remove webhook URL
Brain (memory core used by the MCP server and dashboard)#
Method
Path
Description
POST
/api/v1/instances/{id}/learnStore a lesson in the Brain
POST
/api/v1/instances/{id}/recallRecall and count top Brain lessons
GET
/api/v1/instances/{id}/memoryBrain memory snapshot
GET
/api/v1/instances/{id}/predictionsFailure predictions
GET
/api/v1/instances/{id}/brain-statsBrain search/usage stats
POST
/api/v1/instances/{id}/scanPR risk scan
POST
/api/v1/instances/{id}/ci-outcomeReport CI outcome (closed-loop calibration)
Orgs#
Method
Path
Description
GET
/api/v1/orgs/{id}/savingsOrg-wide savings (ROI)
GET
/api/v1/orgs/:id/lessonsTeam Knowledge Hub lessons feed
GET
/api/v1/orgs/:id/retentionTeam Knowledge Hub retention feed
See Team Knowledge Hub for the full response shapes of the last two.
Semantic Cache (vector token required, no Keycloak JWT)#
Method
Path
Description
POST
/v1/sem/{token}/searchANN search
POST
/v1/sem/{token}/entriesIndex entry
GET
/v1/sem/{token}/entriesList entries
POST
/v1/sem/{token}/entries/batchBatch index (cache warming)
DELETE
/v1/sem/{token}/entries/{id}Delete entry
DELETE
/v1/sem/{token}/flushFlush namespace
GET
/v1/sem/{token}/sizeGet namespace size
POST / GET
/v1/sem/{token}/thresholdSet / get adaptive threshold
POST
/v1/sem/{token}/feedbackRecord feedback for adaptive threshold
POST
/v1/sem/{token}/search/streamStreaming ANN search (SSE)
POST
/v1/sem/{token}/detect-namespaceAuto-detect namespace
GET
/v1/sem/{token}/statsSemantic cache analytics
GET
/v1/sem/{token}/analyticsFull analytics 2.0
GET
/v1/sem/{token}/analytics/anomaliesAnomalies only
GET
/v1/sem/{token}/analytics/recommendRecommendations only
See Semantic Caching for usage examples and SDK snippets.
Billing#
Method
Path
Description
POST
/api/v1/instances/{id}/portal-sessionCreate Stripe billing portal session
GET
/api/v1/billing/invoicesList invoices
GET
/api/v1/billing/subscriptionGet subscription summary
POST
/api/v1/billing/portal-sessionCreate tenant billing portal session
Account (DSGVO data portability)#
Method
Path
Description
GET
/api/v1/account/exportExport account data (DSGVO Art. 20)
DELETE
/api/v1/accountDelete account (DSGVO Art. 17 — right to erasure)
Admin (ADMIN_SECRET_KEY required)#
Method
Path
Description
GET
/api/admin/statsKPI stats
GET
/api/admin/instancesList all instances
GET
/api/admin/nodesList cluster nodes
POST
/api/admin/nodes/provisionProvision a new Hetzner node
Plans, telemetry, warmup, webhooks#
Method
Path
Description
POST / GET / PATCH / DELETE
/api/v1/plansSave, list, get, update, delete a Brain plan
POST
/api/v1/telemetry/mcpRecord MCP Brain funnel event
POST
/v1/cache/{token}/warmWarm KV cache (token-based)
POST
/v1/sem/{token}/warmup/snapshotSemantic cache warmup snapshot
POST
/webhooks/stripeStripe webhook handler
For instance-creation payloads specific to each engine, see Cache Engines and Cluster Mode . To manage instances and keys declaratively instead of by hand, see the Terraform Provider .
← Back to all docs
