API Reference Overview

Base URL, authentication methods, rate limits, pagination, versioning, and request format for the Engramma API.

Base URL

All API requests use the following base URL:

https://api.engramma-memory.com/v1

All requests must be made over HTTPS. HTTP requests are rejected with a 301 redirect.

Authentication

Two authentication methods are supported:

Method	Header	Use case
API Key	`X-API-Key: nx_live_...`	Server-to-server, SDKs, scripts
JWT Bearer	`Authorization: Bearer eyJ...`	Browser apps, user-scoped access

API keys start with nx_live_ (production) or nx_test_ (development). Both are 48 characters long.

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

Rate limits

Rate limits depend on your plan tier:

Plan	Requests/second	Burst (10s window)
Free	10 req/s	50
Starter	50 req/s	250
Professional	200 req/s	1,000
Business	500 req/s	2,500
Enterprise	Custom	Custom

Every response includes rate limit headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per second for your tier
`X-RateLimit-Remaining`	Remaining requests in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait (only on 429 responses)

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 and pagination on GET endpoints.

Pagination

List endpoints return paginated results:

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-indexed)
`per_page`	integer	20	Items per page (max 100)

Paginated responses include:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 142,
    "total_pages": 8,
    "has_next": true,
    "has_prev": false
  }
}

Versioning

The API version is included in the URL path (/v1/). Breaking changes result in a new version. Non-breaking additions (new fields, new endpoints) are added to the current version.

Version	Status	EOL
`v1`	Current, stable	—

When a new version is released, the previous version remains supported for 12 months.

Response format

All successful responses return JSON with consistent structure:

Single resource:

{
  "id": "mem_abc123",
  "text": "...",
  "stored_at": "2026-01-15T10:30:00Z"
}

Collection:

{
  "data": [...],
  "pagination": { ... }
}

Action result:

{
  "success": true,
  "message": "Operation completed"
}

Timestamps

All timestamps are ISO 8601 format in UTC:

2026-01-15T10:30:00Z

IDs

Resource IDs use prefixed format:

Resource	Prefix	Example
Memory	`mem_`	`mem_abc123`
Organization	`org_`	`org_xyz789`
Member	`mem_`	`mem_def456`
API Key	`key_`	`key_ghi012`
Invoice	`inv_`	`inv_jkl345`
Webhook	`wh_`	`wh_mno678`

SDKs

Official SDKs handle authentication, rate limiting, retries, and pagination automatically:

Language	Package	Install
Python	`engramma-cloud`	`pip install engramma-cloud`
JavaScript	`@engramma/sdk`	`npm install @engramma/sdk`
Go	`engramma-go`	`go get github.com/engramma/engramma-go`

Next steps

Authentication — Register, login, MFA endpoints
Memory Core — Store, retrieve, recall, explain
Errors — Error codes and troubleshooting