API Reference Overview

Base URL

All API requests use the following base URL:

https://api.engramma-memory.com

All endpoints are prefixed with /v1/. All requests must be made over HTTPS.

Authentication

Two authentication methods are supported:

API keys are created from the dashboard or via POST /v1/api-keys. They are scoped to an organization.

curl https://api.engramma-memory.com/v1/memory/text/stats \
  -H "X-API-Key: your-api-key"

Rate limits

Rate limits are based on patterns stored and queries per day, not requests per second:

When you exceed your plan's limits, the API returns 429 Too Many Requests with a Retry-After header.

Use GET /v1/usage/summary to check your current consumption.

Request format

• Content-Type: application/json for all request bodies
• Accept: application/json (default)
• Character encoding: UTF-8

All request bodies are JSON. Query parameters are used for filtering on GET endpoints.

Response format

Responses vary by endpoint. Common patterns:

Action result (store):

{
  "success": true,
  "pattern_id": "pat_a7f2c1e9",
  "embedding_dim": 384,
  "patterns_used": 42,
  "patterns_limit": 5000
}

Retrieval result:

{
  "results": [
    {
      "text": "Paris is the capital of France",
      "similarity": 0.94,
      "pattern_id": "pat_a7f2c1e9",
      "metadata": {}
    }
  ],
  "latency_ms": 2.3
}

Error (FastAPI validation):

{
  "detail": [
    {
      "loc": ["body", "text"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Simple error:

{
  "detail": "Not authenticated"
}

Versioning

The current API version is v0.5.0 (pre-release). The version is included in the URL path (/v1/). The v1 prefix will remain stable — only the semantic version will increment.

Timestamps

All timestamps are ISO 8601 format in UTC:

2026-01-15T10:30:00Z

IDs

Pattern IDs use the pat_ prefix (e.g. pat_a7f2c1e9). Other resource IDs are UUIDs.

OpenAPI spec

The full machine-readable spec is available at:

https://api.engramma-memory.com/openapi.json

Or served statically from the documentation site at /openapi.json.

Next steps

• Authentication — Register, login, MFA endpoints
• Memory Core — Store, retrieve, recall (text API)
• Errors — Error codes and troubleshooting