pumaDB Agent memory API docs

Agent memory API docs

REST API for server-side agent memory.

Use pumaDB from backend routes, workers, serverless functions, CLIs, and scripts when your app or agent needs durable JSON memory. Keep puma_live_* keys on the server; do not put them in React bundles, static sites, mobile apps, public repos, or browser-executed code.

Base URL https://api.pumadb.ai
Auth Authorization: Bearer puma_live_...
MCP https://api.pumadb.ai/mcp

Quickstart

Create a server-side memory key.

Request a magic link, verify it, then create a named key for each app or environment. Store the app key in server-side environment variables such as PUMADB_API_KEY.

curl -X POST https://api.pumadb.ai/auth/magic-link \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com"}'

curl -X POST https://api.pumadb.ai/auth/verify \
  -H 'Content-Type: application/json' \
  -d '{"token":"<token-from-magic-link>"}'
curl -X POST https://api.pumadb.ai/v1/_keys \
  -H 'Authorization: Bearer $PUMADB_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-react-api-prod"}'

Calls

Write and read memory rows.

Rows are JSON objects and receive id, created_at, and updated_at. Filters are top-level equality checks on string, number, boolean, or null values.

curl -X POST https://api.pumadb.ai/v1/tasks \
  -H 'Authorization: Bearer $PUMADB_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"ship docs","status":"open"}'
const response = await fetch("https://api.pumadb.ai/v1/tasks?limit=25", {
  headers: {
    Authorization: `Bearer ${process.env.PUMADB_API_KEY}`
  }
});

if (!response.ok) {
  throw new Error(await response.text());
}

const { rows } = await response.json();

React apps

Use a backend or serverless proxy.

A plain React/static app should call your own API route, and that route should call pumaDB with the API key. pumaDB does not expose browser CORS for /v1, because current API keys are full-access bearer secrets.

app.post("/api/tasks", async (req, res) => {
  const response = await fetch("https://api.pumadb.ai/v1/tasks", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PUMADB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(req.body)
  });

  res.status(response.status).send(await response.text());
});

Endpoints

Current REST surface.

POST/auth/magic-link

Request a magic link.

POST/auth/verify

Exchange a magic-link token for an API key.

POST/v1/{table}

Add a JSON row.

GET/v1/{table}

Query rows with filter, sort, and limit.

POST/v1/{table}/batch

Run atomic same-table write operations.

POST/v1/{table}/upsert

Insert or update by natural key.

POST/v1/{table}/update_row

Update one existing row by id.

POST/v1/{table}/update_where

Update rows matching a non-empty filter.

DELETE/v1/{table}

Delete rows matching a non-empty filter.

GET/v1/{table}/count

Count rows.

GET/v1/{table}/versions

List archived row versions.

POST/v1/{table}/restore

Restore an archived row version.

GET/v1/_tables

List tables and row counts.

GET/v1/_export

Export all tables.

POST/v1/_row_links

Create a short-lived JSON viewer/editor link for one stored row.

POST/v1/_query_links

Create a short-lived read-only JSON viewer link for one query result.

POST/v1/_text_field_links

Create a short-lived viewer/editor link for one stored text field.

GET/v1/_keys

List API keys.

POST/v1/_keys

Create a named API key.

DELETE/v1/_keys/{id}

Revoke an API key.

MCP

Use MCP for agent connectors.

Hosted MCP remains available at https://api.pumadb.ai/mcp with OAuth discovery and dynamic client registration. Use REST for app backends and MCP for agent memory tools. See the tool-call reference below for the full agent-facing surface.

MCP tools

Tool-call reference.

These are the tools exposed by the hosted MCP server and local MCP package. They map to the same pumaDB row operations as the REST API, plus safe helper tools for common agent memory types.

Table operations

Create, read, update, count, and clean up JSON rows in named tables.

add

Add a new JSON row to a table. Use when every submission should create a new row. Include an idempotency key when a retry should not duplicate the write.

query

Read rows from a table. Filter by simple equality, sort by one field, and cap results with a limit. MCP query results add short-lived viewer/download links for large text, larger result sets, or explicit includeLink requests.

batch

Run several writes in one request. Use for multiple add, upsert, update_row, update_where, and delete operations against one table. Batches are atomic and capped at 100 operations.

upsert

Insert or replace by natural key. Best for save-or-replace workflows where creating a missing row is acceptable. Do not use it to rename or change key values.

update_row

Patch one existing row by id. Use when you already know the row id. It never creates a row.

update_where

Patch rows matching a non-empty filter. Best for natural edits like changing a stored value. Defaults to exactly one match; bulk updates require allowMultiple.

list_tables

List tables and row counts. Use to inspect what an account has already stored.

count

Count rows in a table. Optionally count only rows matching a simple equality filter.

delete

Delete matching rows. Explicit cleanup only. Requires a non-empty filter and should be used only when the user clearly asks to remove matching memory.

Version history

Recover from overwrites and deletes with archived row versions.

versions

List archived versions of a row. Updates and deletes archive prior content. The last 10 versions are kept for 30 days.

restore

Restore a row to an archived version. Recreates the row if it was deleted. The current value is archived first, so a restore can itself be undone.

Safe memory helpers

Store common agent memory types as inert JSON with safety metadata.

remember

Store typed memory through one consolidated tool. Preferred for new agent writes. Use type resource, code, markdown, command, or config; compatibility remember_* tools store the same inert row shapes.

remember_resource

Store a URL, media/file reference, or documentation note. Stores references plus metadata only; it does not fetch URLs, install dependencies, execute code, or store large binary files.

open_row

Open a stored row in a short-lived JSON viewer/editor. Use when a user wants to inspect, download, or manually edit a complete JSON row outside the chat transcript.

open_text_field

Open a stored text field in a short-lived viewer/editor. Use when a user wants to inspect, download, or manually edit a full Markdown, code, command, or config field without pasting the entire value through chat.

remember_code

Store code or configuration text as an inert snippet. Records text only. SQL snippets get conservative metadata for statement type and destructive risk.

remember_markdown

Store Markdown notes, prompts, instructions, or skill drafts. Markdown is stored as inert text with active_instructions false until a user explicitly asks to use it.

remember_command

Store a shell command as inert text. Records the command, shell, working directory, risk label, and tags without executing anything.

remember_config

Store configuration file content as inert text. Useful for MCP configs, env files, TOML, JSON, YAML, and CI snippets. It is not applied or written to disk.