API overview

The REST API is the contract every other surface is built on: the SDKs and MCP tools call the same endpoints with the same semantics.

Base URL and versioningCopy Anchor Link

All data-plane endpoints live under /v1:

https://memory.empecta.com/v1/...   # the hosted service
https://<your-deployment>/v1/...    # a self-hosted deployment
http://localhost:5199/v1/...        # a typical local self-hosted instance

/v1 covers memory, blocks, user profiles, episodes, procedures, files, categories and the learning loop. Additive changes (new fields, new endpoints) ship in place; breaking changes ship under a new prefix (/v2) with a deprecation window.

The machine-readable OpenAPI document is served at GET /openapi/v1.json.

AuthenticationCopy Anchor Link

Every /v1 request needs a bearer token:

Authorization: Bearer amk_...

Every request also names its workspaceId (in the body for POST/PUT, in the query or path otherwise). A workspace the credential does not hold answers 404, not 403, so its existence does not leak. Capabilities and agent binding are explained in Identity and visibility; key management in Authentication.

Resource groupsCopy Anchor Link

ConventionsCopy Anchor Link

• JSON bodies, camelCase field names. Enum values are strings and case-insensitive on input ("Workspace", "workspace").
• Timestamps are ISO 8601 / RFC 3339. Offsets are accepted and normalized to UTC.
• IDs are GUIDs, except runId, agentId and userId, which are your own strings.
• Lists returned by retrieve are ordered best match first.

ErrorsCopy Anchor Link

Error bodies use application/problem+json:

{
  "type": "https://agentmemory.dev/errors/VALIDATION_FAILED",
  "title": "VALIDATION_FAILED",
  "status": 400,
  "detail": "The request was rejected by domain validation. See traceId for details.",
  "code": "VALIDATION_FAILED",
  "traceId": "0af7651916cd43dd8448eb211c80319c"
}

Branch on status and code, never on detail. detail is a stable, generic sentence; specifics go to the server log under the same traceId — include it in support requests. Some errors add extension members (listed below). A plain 404 for a missing or hidden resource, and some 401/403 responses from the authentication layer, have an empty body.

IdempotencyCopy Anchor Link

Memory mutations accept an optional Idempotency-Key header (1–128 characters; UUIDs recommended):

POST /v1/memory/append · PUT /v1/memory/{id} · DELETE /v1/memory/{id} · POST /v1/memory/{id}/share · POST /v1/memory/consolidate

• The first successful (2xx) response is stored for 24 hours, per tenant — status included, so a replayed delete answers 204 again rather than 404.
• Retrying with the same key and the same request (path, query and body) returns the stored response with Idempotency-Replayed: true. The mutation does not run twice.
• The same key with a different request — another body, another memory ID, another workspace — or while the first request is still in flight answers 409 IDEMPOTENCY_CONFLICT.
• Failed responses are not stored, so a failed request can be retried with the same key.
• A key longer than 128 characters is rejected with 422.

Without the header, behaviour is unchanged. Append's semantic de-duplication (near-duplicate merging) applies independently.

ETags and conditional updatesCopy Anchor Link

PUT /v1/memory/{id} supports optimistic concurrency. Read the memory's version, then send it back:

If-Match: "7"

"7", W/"7" and 7 are all accepted; * or no header means no precondition. A stale version answers 412 precondition_failed with currentVersion and nothing is written. A successful update returns the new version in both the body and the ETag header. See Updating and forgetting.

Rate limits and quotasCopy Anchor Link

• Request rate is limited per tenant in fixed one-minute windows. Anonymous traffic gets a tighter per-IP window, and an optional per-workspace fairness window can apply to API-key traffic. The limits are deployment configuration (see Configuration).
• A rejected request answers 429 RATE_LIMITED with Retry-After: 60.
• Plan quotas — such as monthly metered operations on the memory endpoints — answer 429 QUOTA_EXCEEDED with Retry-After and the resource, limit and current values.

Treat every 429 and 503 as retryable after Retry-After, with backoff.

Request limitsCopy Anchor Link

Out-of-range sizes are clamped, not rejected:

Hard caps (exceeding them is an error):

HealthCopy Anchor Link

GET /api/health and GET /api/version are unauthenticated and outside /v1. Self-hosted deployments also expose /health/live and /health/ready — see Operations.