AgentRAM API Reference

Creates a new account and emails you an API key with 1,000 free credits. For security, the key is sent by email rather than in the response, and the response is identical whether or not the email is already registered. One account per email address.

{
  "success": true,
  "message": "Check your email for your API key."
}

Stores a value under a key for a given agent. Writing to an existing key updates the value. No duplicates are created.

{
  "success": true,
  "data": {
    "agent_id": "agent-01",
    "key": "user_pref",
    "credits_remaining": 999
  }
}

Retrieves a stored value by agent ID and key. Returns 404 if the memory does not exist, and refunds the credit.

{
  "success": true,
  "data": {
    "agent_id": "agent-01",
    "key": "user_pref",
    "value": "prefers short answers",
    "created_at": "2026-05-09T18:00:00.000Z",
    "credits_remaining": 998
  }
}

Permanently removes a stored memory. This cannot be undone.

{
  "success": true,
  "data": { "deleted": true, "credits_remaining": 997 }
}

Returns the current credit balance for your account. This endpoint never deducts a credit. Safe to call as often as needed.

{
  "success": true,
  "data": {
    "email": "you@example.com",
    "credits": 997
  }
}

Returns all memories stored under a given agent ID, ordered by most recently written. Expired memories are silently excluded.

{
  "success": true,
  "data": [
    { "key": "user_lang", "value": "French", "created_at": "...", "expires_at": null },
    { "key": "tone", "value": "formal", "created_at": "...", "expires_at": null }
  ],
  "credits_remaining": 996
}

Case-insensitive text search across both the key and value fields for a given agent. Returns matching memories ordered by most recent. No embeddings or configuration required.

{
  "success": true,
  "data": [
    { "key": "user_lang", "value": "French", "created_at": "..." }
  ],
  "credits_remaining": 995
}

Creates a new shared namespace and returns a unique namespace key. Free, costs no credits. Any agent with a valid API key and the namespace key can then read and write to that namespace.

{
  "success": true,
  "data": { "namespace_key": "ns_a1b2c3d4...", "label": "team-alpha" }
}

Writes a value to a shared namespace. Any API key holder who knows the namespace key can write. Supports optional TTL.

Retrieves a value from a shared namespace by key.

Returns all memories in a shared namespace, ordered by most recent. Expired memories are silently excluded.

Sends a single-use recovery link to the given email if an account exists. Always returns the same generic success response, whether or not the email is registered, to prevent anyone discovering which addresses have accounts.

{
  "success": true,
  "message": "If this email exists in our system, you'll receive recovery instructions shortly."
}

The recovery link expires 30 minutes after it is sent and can be used only once. Requesting a new link invalidates any previous one for the same email.

Validates a recovery token and issues a new API key for the account. The token is consumed on first use, so a second call with the same token is rejected. Because keys are stored hashed and never in plain text, the original key cannot be shown again, so recovery rotates it instead. The old key stops working immediately, which also means a leaked key is revoked the moment you recover. Update anywhere the old key was deployed.

{
  "success": true,
  "data": {
    "email": "you@example.com",
    "api_key": "agentram_7f3a9b2c...",
    "credits": 1000
  }
}

A used, expired, or invalid token returns success: false with a message explaining that a new link must be requested. Recovering also sends a notification email to the account, so an unexpected recovery is visible to the owner.

Records a value as a new assertion. Pass supersedes to say which earlier assertion this one replaces. Without it the write simply appends: if something is already live for the key, the key becomes contested and the next read returns 409 rather than guessing between the two.

{
  "success": true,
  "data": {
    "assertion_id": "9c1f...  ",
    "agent_id": "agent-01",
    "key": "invoice_number",
    "value": "1044",
    "state": "live",
    "written_by": "billing-agent",
    "written_at": "2026-07-31T09:14:22Z"
  },
  "credits_remaining": 998
}

Returns 409 if the assertion named in supersedes is no longer live, meaning another writer changed the key first. Re-read the key and retry. Returns 400 if it does not reference an assertion under this agent and key.

Ends a fact with nothing replacing it. Use this when something stopped being true and no new value took its place. Afterwards the key has no current value, but the history survives: the retirement is itself recorded as an assertion with its own author and timestamp, so you can always see who ended it and when. That is the difference from DELETE /memory, which erases and leaves no trace.

{
  "success": true,
  "data": {
    "assertion_id": "4b7e...  ",
    "key": "invoice_number",
    "state": "retired",
    "cleared": 1
  },
  "credits_remaining": 997
}

cleared is how many live assertions the retirement ended. More than one means the key was contested at that moment. Returns 404 if nothing was live to retire.

Returns the assertion that is currently true for a key, with its provenance and the assertion_id you need to supersede it. Returns 404 when nothing is live, whether the key was never asserted, was retired, or passed its valid_until.

{
  "success": true,
  "data": {
    "key": "invoice_number",
    "value": "1044",
    "assertion_id": "9c1f...  ",
    "written_by": "billing-agent",
    "written_at": "2026-07-31T09:14:22Z"
  },
  "credits_remaining": 996
}

When a key is contested. If two agents write the same key without either knowing about the other, there are two live values and neither replaced the other. Returning one of them would be a guess, and silently reading a stale value is the exact failure assertions exist to prevent. So the read returns 409 with both, newest first, and you decide.

{
  "success": false,
  "error": "Key has conflicting live assertions",
  "conflict": {
    "key": "invoice_number",
    "assertions": [
      { "assertion_id": "9c1f...  ", "value": "1044", "written_by": "agent-a" },
      { "assertion_id": "3d80...  ", "value": "1099", "written_by": "agent-b" }
    ]
  }
}

Resolve it by asserting a new value that supersedes one of them. The others stop being current at the same time, so the key is settled in one write.

Everything currently true for an agent, one entry per key. Retired keys and keys past their valid_until do not appear.

{
  "success": true,
  "data": {
    "assertions": [
      {
        "key": "deploy_target",
        "value": "production",
        "contested": false,
        "assertion_count": 1,
        "assertion_id": "7a22...  ",
        "written_by": "deploy-agent"
      },
      {
        "key": "invoice_number",
        "contested": true,
        "assertion_count": 2
      }
    ],
    "truncated": false
  },
  "credits_remaining": 995
}

A contested key is flagged and its value is withheld, for the same reason the single-key read refuses one: guessing across a list is the same mistake as guessing on one key. Read that key on its own to see the competing values. truncated is true when more entries exist beyond the limit.

Every assertion ever written for a key, newest first. This is the audit trail: what each value was, who wrote it, when, and which one it replaced. It is what turns "why does the agent still think that?" into something you can read.

{
  "success": true,
  "data": {
    "key": "invoice_number",
    "assertions": [
      { "value": "1044", "state": "live",       "written_by": "agent-a" },
      { "value": "1043", "state": "superseded", "written_by": "agent-a" }
    ],
    "truncated": false
  },
  "credits_remaining": 994
}

state is live for the current value, superseded for one that was replaced, and retired for a retirement marker.