API Documentation

Ragionex Memory is the public API for saving and retrieving persistent memory for AI agents. Accounts own Vaults and API keys. Each record request selects a Vault. Requests and responses use JSON.

Base URL

All API requests are made to:

https://api.ragionex.com

Authentication

Every /v1/memory/ endpoint uses the X-API-Key header. Send the key itself as the header value.

Sign in at app.ragionex.com/keys and create a named API key. New accounts start with a Vault named My vault, which is the account default. Copy the secret when it is created; the key list cannot reveal it later.

A key belongs to your account and carries fixed permissions chosen from read, create, update and delete. You can rename or revoke a key. It works in every Vault you own or that is shared with your account. To change its permissions, create a replacement key. If your account's active-key limit is reached, revoke an unused key first.

Vaults and keys are managed in the signed-in dashboard. They are not managed through the Memory API or MCP tools.

Names must contain 1–100 characters after trimming, without control or bidirectional formatting characters. You can rename any Vault you own and permanently delete any owned Vault except your current default; to delete the default, first make another Vault you own the default. Deleting a Vault removes its memories, history and trash. Renaming a Vault does not change its ID. Revoking a key does not delete its records.

Use GET /v1/memory/identity to see your account ID, key label and permissions, and all owned and shared Vaults you can reach, with their access, effective permissions and default flag. Identity needs a valid key but no particular record permission. Other operations require the grant listed in the permission table.

X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Vault Selection

For a new record operation, send X-Ragionex-Vault-Id to choose a Vault. Without this header, the request uses your account's default Vault.

For project setup and the dashboard sharing steps, read Vaults: projects and sharing.

Find Vault IDs with GET /v1/memory/identity. Choose an owned or shared Vault from its vaults array. Send exactly one lowercase, 32-character hexadecimal Vault ID; a malformed or repeated header returns HTTP 422 with validation_error. An unavailable Vault or one your account cannot access returns HTTP 404 with vault_not_found.

curl "https://api.ragionex.com/v1/memory/list?limit=50" \
  -H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Ragionex-Vault-Id: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"

Replace both example values with your key and a reachable Vault ID. The Vault ID belongs in the header, not the JSON body or a query parameter. Use the same selected Vault for reads, status checks, edits and deletion. A record reply's vault_id identifies where that record belongs.

Identity lists reachable Vaults and ignores the selection header. A matching write retry stays bound to the Vault where that request token was first accepted, even if the default or header changes.

For agents using MCP, put the Vault ID in RAGIONEX_MEMORY.jsonc in the project folder. The connector sends the selection header for you.

Memory API

Use the endpoint reference to save, search and manage records in the selected Vault.