REST API Reference
Access your capsule memories over standard HTTP. Same data, same limits, no MCP client required.
Base URL
https://agimem.dev/api/restAuthentication
All requests require a Bearer token. Use the same API key from your capsule — each key is scoped to exactly one capsule.
Authorization: Bearer agm_your_api_keyKeys start with agm_ and are 40 characters long — see the API key format reference.
Rate Limits
60 requests per minute per account, shared across MCP and REST. Rate limited responses return 429 with a Retry-After: 60 header.
Errors
All errors return JSON with an error field:
{ "error": "description of what went wrong" }400Bad request401Invalid or missing API key404Resource not found409Limit exceeded429Rate limited500Internal server errorMemory
PUT/memory
Store or update a memory. Missing tags are created automatically within the capsule tag limit. Returns 201 for new keys, 200 for updates.
Request Body
{
"key": "user-preferences",
"value": "Prefers dark mode, concise answers",
"tags": ["settings", "ui"],
"ttlMinutes": 1440
}Response
{
"key": "user-preferences",
"stored": true,
"tags": ["settings", "ui"],
"expiresAt": "2026-05-11T12:00:00.000Z",
"isNew": true
}GET/memory?key=X
Retrieve a memory by key. Returns the value, tags, timestamps, and expiration.
Query Parameters
keyrequiredThe memory key to retrieveResponse
{
"key": "user-preferences",
"value": "Prefers dark mode, concise answers",
"tags": ["settings", "ui"],
"expiresAt": "2026-05-11T12:00:00.000Z",
"createdAt": "2026-05-10T12:00:00.000Z",
"updatedAt": "2026-05-10T12:00:00.000Z"
}DELETE/memory?key=X
Delete a memory by key.
Query Parameters
keyrequiredThe memory key to deleteResponse
{ "key": "user-preferences", "deleted": true }List & Search
GET/memories
List non-expired memories with their keys and last-updated timestamps. Paginated.
Query Parameters
pagePage number (default 1)pageSizeItems per page (1–200, default 50)prefixOnly include keys starting with this prefix (case-sensitive), e.g. project.acme.Response
{
"keys": [
{ "key": "config", "updatedAt": "2026-05-10T12:00:00.000Z" },
{ "key": "notes", "updatedAt": "2026-05-09T08:00:00.000Z" }
],
"page": 1,
"pageSize": 50,
"totalCount": 2,
"totalPages": 1
}GET/memories?q=search
Search memories by topic. Matches any query word in keys or values (including word forms like plurals) or the exact text, best matches first.
Query Parameters
qrequiredSearch querylimitMax results (1–50, default 20)Response
{
"results": [
{ "key": "config", "preview": "Dark mode enabled, font size 14..." }
],
"count": 1
}GET/memories/keys
List only key names (no values). Lighter than full list.
Query Parameters
prefixOnly include keys starting with this prefix (case-sensitive), e.g. project.acme.Response
{ "keys": ["config", "notes", "preferences"] }GET/memories/count
Get the number of non-expired memories and the capsule limit.
Query Parameters
prefixOnly include keys starting with this prefix (case-sensitive), e.g. project.acme.Response
{ "count": 42, "limit": 200 }GET/memories/exists?key=X
Check whether a key exists without fetching its value.
Query Parameters
keyrequiredThe key to checkResponse
{ "key": "config", "exists": true }DELETE/memories
Delete all memories in the capsule.
Response
{ "cleared": true }Bulk Operations
POST/memories/bulk/set
Store multiple memories in one request (up to 20 items).
Request Body
{
"items": [
{ "key": "k1", "value": "v1", "tags": ["t1"] },
{ "key": "k2", "value": "v2", "ttlMinutes": 60 }
]
}Response
{
"storedCount": 2,
"errorCount": 0,
"results": [""k1": stored with 1 tag(s)", ""k2": stored"]
}POST/memories/bulk/get
Retrieve multiple memories by key (up to 50 keys).
Request Body
{ "keys": ["k1", "k2", "k3"] }Response
{
"items": [
{ "key": "k1", "found": true, "value": "v1", "tags": ["t1"] },
{ "key": "k2", "found": true, "value": "v2", "tags": [] },
{ "key": "k3", "found": false }
],
"foundCount": 2,
"missingCount": 1
}POST/memories/bulk/delete
Delete multiple memories by key (up to 50 keys).
Request Body
{ "keys": ["k1", "k2"] }Response
{
"deletedCount": 2,
"missingCount": 0,
"results": [
{ "key": "k1", "deleted": true },
{ "key": "k2", "deleted": true }
]
}Tags
GET/tags
List all tags in the capsule.
Response
{ "tags": ["config", "notes", "ui"] }POST/tags
Create a new tag. Returns 201 if created, 200 if it already exists.
Request Body
{ "name": "my-tag" }Response
{ "name": "my-tag", "created": true }DELETE/tags?name=X
Delete a tag and unlink it from all memories.
Query Parameters
namerequiredThe tag name to deleteResponse
{ "name": "my-tag", "deleted": true }GET/tags/memories?tag=X
List memory keys that have a specific tag.
Query Parameters
tagrequiredTag to filter byResponse
{ "keys": ["config", "preferences"] }POST/tags/memories
List memory keys matching all given tags (AND filter).
Request Body
{ "tags": ["config", "ui"] }Response
{ "keys": ["preferences"] }Capsule
GET/capsule
Get a summary of the capsule: name, description, usage, and limits.
Response
{
"name": "my-project",
"description": "Production agent memory",
"memoryCount": 42,
"memoryLimit": 200,
"tagCount": 5,
"tagLimit": 20,
"lastUsed": "2026-05-10T12:00:00.000Z"
}