Docs

Memory REST API reference

The memory REST API lets your own code add, list, search and delete memories over HTTPS. Every route below is under https://agentics.you/v1/. The reference on this page is generated from the OpenAPI 3.1 description at /developers/openapi.yaml, so the two always agree. Agents in MCP clients use the MCP server instead.

Authentication

Send an org API key as a bearer token. A workspace admin creates one in the console under API keys. It starts ak_ and is shown once.

bash

export AGENTICS_API_KEY="ak_..."
curl https://agentics.you/v1/memories \
  -H "Authorization: Bearer $AGENTICS_API_KEY"

A key reaches only the namespaces it is bound to. A new key is bound to your workspace's default namespace, so it works on its first call. A signed-in workspace admin can change a key's namespaces with PUT /v1/keys/{key_id}/namespaces, under Keys below. A key created with the memory.read or memory.write scope is narrowed further: reads need either, writes need memory.write. The console's own pages use the signed-in session instead of a key. A virtual key (vk_) and an agent key (agk_mcp_) are not accepted here. See Scoping.

Conventions

Bodies are JSON, and every field is snake_case.
A list answers { "data": [...], "next_cursor": "..." }. Pass next_cursor back as cursor until it is null.
An error answers { "error": { "code": "...", "message": "...", "details": {...} } }. Match on code. Every code, its status and what to do is on Errors and limits.
A write is a receipt. A memory's receipt_id and the receipt_id of a delete can be checked like any other receipt. See Receipts.
The webhook routes under Webhooks also need an x-agentics-agent header naming the agent that owns the webhook. When a matching memory is admitted, written over REST or with MCP, the webhook gets a signed POST.
Search is POST /v1/memories/search: meaning and keyword fused into one score, with each hit's receipt and why it ranked. GET /v1/memories?q= is a plain full-text filter on the list, newest first.

Add a memory, then find it

bash

curl https://agentics.you/v1/memories \
  -H "Authorization: Bearer $AGENTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Billing runs on Neon. Decided 2026-10-01.","metadata":{"team":"billing"}}'

curl "https://agentics.you/v1/ingest/$JOB_ID" \
  -H "Authorization: Bearer $AGENTICS_API_KEY"

curl https://agentics.you/v1/memories/search \
  -H "Authorization: Bearer $AGENTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"which database runs billing?"}'

The add answers 202 with job_id and memory_id. The memory is searchable once its job reaches done. Each hit has score, why and the receipt_hash of its write.

Memories

List and search memories

GET /v1/memories

Ready memories, newest first. q is a full-text search (web search syntax: quoted phrases, OR, and -word). Use cursor for paging; page is also accepted, up to offset 10000.

Auth: an API key (Authorization: Bearer ak_…), or a signed-in session.

Parameter	In	Type	Notes
`q`	query	string
`namespace_id`	query	string	One namespace id, or several separated by commas.
`user_id`	query	string
`agent_id`	query	string
`app_id`	query	string
`run_id`	query	string
`include_playground`	query	boolean, default false
`limit`	query	integer, 1 to 100, default 25
`cursor`	query	string
`page`	query	integer	1-based. Not with cursor.
`sort`	query	one of: newest

Status	Meaning	Body
`200`	A page of memories	MemoryList
`400`	The request was malformed. See error.code.	MemoryError
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError

Add a memory

POST /v1/memories

Stores the memory as pending and queues a job that makes it ready. Poll GET /v1/ingest/{job_id}. The same content in the same namespace returns the existing memory with duplicate true and status 200. The write is a receipt. Emails, phone numbers, card and IBAN numbers, keys and tokens in content and metadata are stored as [redacted]; a workspace set to refuse them answers 400 content_rejected. The workspace's write rules apply: Pause all answers 423 tenant_paused, and a rule that asks the owner answers 409 approval_required with details.approval_id; retry with approval_id once it is approved.

Auth: an API key (Authorization: Bearer ak_…), or a signed-in session.

Body field	Type		Notes
`content`	string	required	At most 1048576 bytes of UTF-8.
`namespace`	string		A namespace id or name. Defaults to the workspace's default namespace.
`metadata`	object		At most 65536 bytes as JSON.
`source`	string or null
`playground`	boolean		Marks a test memory. Lists leave it out unless include_playground is true.
`approval_id`	string		The Needs-you approval from a 409 approval_required. Send it on the retry once a person approved the write.

Status	Meaning	Body
`200`	Already stored in this namespace	MemoryAccepted
`202`	Accepted and queued	MemoryAccepted
`400`	The request was malformed. See error.code.	MemoryError
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`402`	Free is at its monthly actions (plan_action_limit) or its stored memories (plan_memory_limit). Nothing was written.	PlanLimit
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`409`	The request conflicts with the current state. See error.code.	MemoryError
`413`	content_too_large or metadata_too_large (details.limit_bytes says the limit), or body_too_large when the whole request body is over 8 MiB.	MemoryError
`423`	tenant_paused: the workspace owner paused every agent (Pause all). Nothing was written. Only the owner can resume.	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError
`503`	receipt_unavailable: the write could not be recorded as a receipt. meter_unavailable: the plan meter could not be read. approval_unavailable: a write rule needs the owner's approval and the request could not be filed. Nothing was written. Retry; meter_unavailable sends Retry-After.	MemoryError

Search memories

POST /v1/memories/search

Ranks ready memories by meaning and by keyword, fused into one score, across the namespaces the caller can read. The REST form of the MCP recall and get_context tools. Each hit carries its write receipt_hash, a score from 0 to 1, and why it ranked. When the dense arm cannot run, mode is keyword and degraded names the reason; nothing falls back silently. Each search writes one memory.recall receipt; if that receipt cannot be written, no hits are returned (503 recall_receipt_unavailable). A key narrowed with scopes needs memory.read or memory.write.

Auth: an API key (Authorization: Bearer ak_…), or a signed-in session.

Body field	Type		Notes
`query`	string, 1 to 2000	required
`namespace_ids`	string (uuid) list, 1 to 100		Defaults to every namespace the caller can read.
`agent_id`	string		Only memories this agent wrote.
`k`	integer, 1 to 50, default 8		How many hits.
`token_budget`	integer, 200 to 32000, default 4000		Bounds the reply. The best hit always comes back, cut to fit.
`filters`	object

Status	Meaning	Body
`200`	Ranked hits	MemorySearchResult
`400`	The request was malformed. See error.code.	MemoryError
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError
`503`	recall_receipt_unavailable: the search could not be recorded as a memory.recall receipt, so no hits were returned. Wait Retry-After seconds and retry.	MemoryError

Delete many memories

POST /v1/memories/bulk-delete

Without approval_receipt_id, a person is asked in Needs you and the call answers 409 approval_required with details.approval_id. Once approved, repeat it with approval_receipt_id for exactly the same ids. Each delete is a receipt.

Auth: an API key (Authorization: Bearer ak_…), or a signed-in session.

Body field	Type		Notes
`ids`	string (uuid) list, 1 to 1000	required
`approval_receipt_id`	string

Status	Meaning	Body
`200`	Deleted	JSON object
`400`	The request was malformed. See error.code.	MemoryError
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`409`	The request conflicts with the current state. See error.code.	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError
`503`	receipt_unavailable: the write could not be recorded as a receipt. meter_unavailable: the plan meter could not be read. approval_unavailable: a write rule needs the owner's approval and the request could not be filed. Nothing was written. Retry; meter_unavailable sends Retry-After.	MemoryError

Get a memory

GET /v1/memories/{memory_id}

Auth: an API key (Authorization: Bearer ak_…), or a signed-in session.

Parameter	In	Type		Notes
`memory_id`	path	string (uuid)	required

Status	Meaning	Body
`200`	The memory, with its full content	Memory
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError

Delete a memory

DELETE /v1/memories/{memory_id}

The delete is a receipt. The write receipt keeps its hash.

Auth: an API key (Authorization: Bearer ak_…), or a signed-in session.

Parameter	In	Type		Notes
`memory_id`	path	string (uuid)	required

Status	Meaning	Body
`200`	Deleted	MemoryDeleted
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError
`503`	receipt_unavailable: the write could not be recorded as a receipt. meter_unavailable: the plan meter could not be read. approval_unavailable: a write rule needs the owner's approval and the request could not be filed. Nothing was written. Retry; meter_unavailable sends Retry-After.	MemoryError

Export memories

GET /v1/memories/export

Every memory in the namespaces the caller can read, ready ones and pending ones, a page at a time in the agentics-memories/1 format. A page stops at about 8 MiB of content and metadata. Follow next_cursor until it is null. Needs an owner or admin session (403 admin_required), or a key not narrowed to memory.read or memory.write (403 insufficient_scope).

Auth: an API key (Authorization: Bearer ak_…), or a signed-in session.

Parameter	In	Type		Notes
`cursor`	query	string
`limit`	query	integer

Status	Meaning	Body
`200`	One page of the export	MemoryExport
`400`	The request was malformed. See error.code.	MemoryError
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError

Ingest

Get an ingest job

GET /v1/ingest/{job_id}

Poll until terminal is true, waiting poll_after_ms between calls.

Auth: an API key (Authorization: Bearer ak_…), or a signed-in session.

Parameter	In	Type		Notes
`job_id`	path	string (uuid)	required

Status	Meaning	Body
`200`	The job	IngestJob
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError

Retry an ingest job

POST /v1/ingest/{job_id}/retry

Only a failed or stalled job, or one with no progress for 15 minutes. Otherwise 409 job_not_retryable.

Auth: an API key (Authorization: Bearer ak_…), or a signed-in session.

Parameter	In	Type		Notes
`job_id`	path	string (uuid)	required

Status	Meaning	Body
`202`	Queued again	IngestJob
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`409`	The request conflicts with the current state. See error.code.	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError

List ingest jobs

GET /v1/ingest

The caller's jobs, newest first, each with its source and label. Filter by stage with a comma-separated list.

Auth: an API key (Authorization: Bearer ak_…), or a signed-in session.

Parameter	In	Type	Notes
`stage`	query	string	Comma-separated stages. An unknown stage answers invalid_stage.
`cursor`	query	string
`limit`	query	integer

Status	Meaning	Body
`200`	A page of jobs	JSON object
`400`	The request was malformed. See error.code.	MemoryError
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError

Import text, a file or a URL

POST /v1/ingest

One entry point for a text paste, a file (PDF and text types; PDF text is extracted, and a PDF with no text layer is refused) or a URL (fetched server side: http or https only, no credentials, no private, loopback or link-local hosts, 10 seconds, 5 MB). Each becomes a POST /v1/memories, with the same job, pipeline and write receipt. Extracted text over 1 MiB is refused with content_too_large, never cut.

Auth: an API key (Authorization: Bearer ak_…), or a signed-in session.

Body field	Type		Notes
`kind`	one of: text, file, url	required
`content`	string		kind text. Up to 1 MiB.
`source`	string		kind text. import:file marks a part of a file split in the browser; anything else is import:text.
`filename`	string		kind file.
`content_type`	string		kind file.
`data_base64`	string		kind file. The file, base64. Up to 5 MB.
`url`	string, at most 2048		kind url. http or https.
`namespace`	string		The namespace id or name. The default namespace when left out.
`metadata`	object
`playground`	boolean

Status	Meaning	Body
`200`	Already stored in this namespace	MemoryAccepted
`202`	Accepted and queued	MemoryAccepted
`400`	The request was malformed. See error.code.	MemoryError
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`402`	Free is at its monthly actions (plan_action_limit) or its stored memories (plan_memory_limit). Nothing was written.	PlanLimit
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`409`	The request conflicts with the current state. See error.code.	MemoryError
`413`	content_too_large or metadata_too_large (details.limit_bytes says the limit), or body_too_large when the whole request body is over 8 MiB.	MemoryError
`415`	unsupported_file or unsupported_url: Import reads PDF and text files, and HTML or text pages.	MemoryError
`422`	no_text or unreadable_pdf: there is no text to remember. Nothing was written.	MemoryError
`423`	tenant_paused: the workspace owner paused every agent (Pause all). Nothing was written. Only the owner can resume.	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError
`502`	fetch_failed: the URL could not be fetched, answered an error, or redirected too often.	MemoryError
`503`	receipt_unavailable: the write could not be recorded as a receipt. meter_unavailable: the plan meter could not be read. approval_unavailable: a write rule needs the owner's approval and the request could not be filed. Nothing was written. Retry; meter_unavailable sends Retry-After.	MemoryError

Namespaces

List namespaces

GET /v1/namespaces

A key sees the namespaces it is bound to. A session sees every namespace in the workspace. Ordered by name.

Auth: an API key (Authorization: Bearer ak_…), or a signed-in session.

Parameter	In	Type	Notes
`cursor`	query	string
`limit`	query	integer, 1 to 1000, default 1000
`include`	query	one of: stats	stats adds memory_count and last_activity_at to each namespace.

Status	Meaning	Body
`200`	Namespaces	NamespaceList
`400`	The request was malformed. See error.code.	MemoryError
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError

Create a namespace

POST /v1/namespaces

A signed-in workspace admin only. A key gets namespace_management_forbidden.

Auth: a signed-in session.

Body field	Type		Notes
`name`	string, 1 to 64	required	Trimmed. No control characters. Unique in the workspace.

Status	Meaning	Body
`201`	Created	Namespace
`400`	The request was malformed. See error.code.	MemoryError
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`409`	The request conflicts with the current state. See error.code.	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError

Get a namespace

GET /v1/namespaces/{namespace_id}

Auth: an API key (Authorization: Bearer ak_…), or a signed-in session.

Parameter	In	Type		Notes
`namespace_id`	path	string (uuid)	required

Status	Meaning	Body
`200`	The namespace	Namespace
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError

Rename a namespace

PATCH /v1/namespaces/{namespace_id}

A signed-in workspace admin only.

Auth: a signed-in session.

Parameter	In	Type		Notes
`namespace_id`	path	string (uuid)	required

Body field	Type		Notes
`name`	string, 1 to 64	required	Trimmed. No control characters. Unique in the workspace.

Status	Meaning	Body
`200`	Renamed	Namespace
`400`	The request was malformed. See error.code.	MemoryError
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`409`	The request conflicts with the current state. See error.code.	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError

Delete a namespace

DELETE /v1/namespaces/{namespace_id}

A signed-in workspace admin only. The default namespace cannot be deleted (cannot_delete_default_namespace). A namespace that holds memories answers namespace_not_empty unless move_to names another namespace, in the body or the query, to move them to first.

Auth: a signed-in session.

Parameter	In	Type		Notes
`namespace_id`	path	string (uuid)	required
`move_to`	query	string

Body field	Type		Notes
`move_to`	string

Status	Meaning	Body
`200`	Deleted	JSON object
`400`	The request was malformed. See error.code.	MemoryError
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`409`	The request conflicts with the current state. See error.code.	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError

Keys

List a key's namespaces

GET /v1/keys/{key_id}/namespaces

A signed-in person only. API keys get user_session_required.

Auth: a signed-in session.

Parameter	In	Type		Notes
`key_id`	path	string (uuid)	required	The id of an org API key in this workspace.

Status	Meaning	Body
`200`	The key's namespaces	KeyNamespaces
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError

Set a key's namespaces

PUT /v1/keys/{key_id}/namespaces

A signed-in workspace admin only. Replaces the whole list. An empty list denies the key everything (key_has_no_namespaces on its next call).

Auth: a signed-in session.

Parameter	In	Type		Notes
`key_id`	path	string (uuid)	required	The id of an org API key in this workspace.

Body field	Type		Notes
`namespace_ids`	string list, at most 1000	required	Namespace ids or names.

Status	Meaning	Body
`200`	The key's namespaces now	KeyNamespaces
`400`	The request was malformed. See error.code.	MemoryError
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError

Webhooks

List an agent's memory webhooks

GET /v1/webhooks

The REST form of the MCP list_subscriptions tool. The webhook URL is never returned, only its host. On only while memory tools are on (404 otherwise). 120 requests a minute per client address.

Auth: an API key (Authorization: Bearer ak_…), or a signed-in session.

Parameter	In	Type		Notes
`x-agentics-agent`	header	string	required	The agent that owns the webhook, by its agent_identities id or its token.

Status	Meaning	Body
`200`	The agent's webhooks	JSON object
`400`	The request was malformed. See error.code.	MemoryError
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError
`503`	memory_unavailable: the subscription store could not be reached. Nothing was changed. Retry.	MemoryError

Create a memory webhook

POST /v1/webhooks

The REST form of the MCP subscribe tool. When a memory that matches the pattern is admitted, whether written over REST or with MCP, agentics.you sends a signed POST (x-agentics-signature) to the URL, retries it, then dead-letters it. Up to 50 per agent and 500 per workspace. A key narrowed with scopes needs memory.write.

Auth: an API key (Authorization: Bearer ak_…), or a signed-in session.

Parameter	In	Type		Notes
`x-agentics-agent`	header	string	required	The agent that owns the webhook, by its agent_identities id or its token.

Body field	Type		Notes
`webhook_url`	string (uri), at most 2000	required	A public https URL.
`name`	string
`pattern`	WebhookPattern	required	What a memory must match. At least one field.

Status	Meaning	Body
`201`	The new webhook	Webhook
`400`	The request was malformed. See error.code.	MemoryError
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`409`	The request conflicts with the current state. See error.code.	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError
`503`	memory_unavailable: the subscription store could not be reached. Nothing was changed. Retry.	MemoryError

Delete a memory webhook

DELETE /v1/webhooks/{webhook_id}

The REST form of the MCP unsubscribe tool. Only the agent that owns the webhook can delete it.

Auth: an API key (Authorization: Bearer ak_…), or a signed-in session.

Parameter	In	Type		Notes
`webhook_id`	path	string (uuid)	required
`x-agentics-agent`	header	string	required	The agent that owns the webhook, by its agent_identities id or its token.

Status	Meaning	Body
`200`	Deleted	JSON object
`400`	The request was malformed. See error.code.	MemoryError
`401`	No credential, an expired session, or a key with no workspace (unauthorized, session_expired).	MemoryError
`403`	The caller is not allowed (credential_not_supported, csrf, workspace_role_required, read_only, admin_required, key_has_no_namespaces, or a scope code such as namespace_out_of_scope).	MemoryError
`404`	Missing, out of the caller's workspace, or the memory API is not on for this workspace (not_found, feature_not_enabled, route_not_found, or the resource's own not_found code).	MemoryError
`429`	rate_limited. 300 requests a minute per client address, and per workspace 600 writes and 300 searches a minute. Retry-After says how many seconds to wait.	MemoryError
`503`	memory_unavailable: the subscription store could not be reached. Nothing was changed. Retry.	MemoryError

Schemas

MemoryIn

Field	Type		Notes
`content`	string	required	At most 1048576 bytes of UTF-8.
`namespace`	string		A namespace id or name. Defaults to the workspace's default namespace.
`metadata`	object		At most 65536 bytes as JSON.
`source`	string or null
`playground`	boolean		Marks a test memory. Lists leave it out unless include_playground is true.
`approval_id`	string		The Needs-you approval from a 409 approval_required. Send it on the retry once a person approved the write.

MemoryAccepted

Field	Type		Notes
`job_id`	string (uuid)	required
`memory_id`	string (uuid)	required
`duplicate`	boolean	required	True when the same content is already in this namespace. No new job is queued.
`stage`	one of: queued, extracting, chunking, embedding, indexing, done, failed	required

Memory

Field	Type		Notes
`id`	string (uuid)	required
`namespace_id`	string (uuid)	required
`content`	string	required
`content_hash`	string	required
`metadata`	object	required
`source`	string or null	required
`provenance`	Provenance	required	Who wrote the memory. Set by the server from the caller, never from the request body.
`playground`	boolean	required
`status`	one of: pending, ready, failed	required
`receipt_id`	string or null	required	The receipt of the write, once it is recorded.
`created_at`	string (date-time)	required
`updated_at`	string (date-time)	required

MemorySummary

Field	Type		Notes
`id`	string (uuid)	required
`namespace_id`	string (uuid)	required
`excerpt`	string	required	The first 280 characters of the content, ending in an ellipsis when cut.
`content_hash`	string	required
`metadata`	object	required	The first 20 keys.
`metadata_key_count`	integer	required
`metadata_truncated`	boolean	required
`source`	string or null	required
`provenance`	Provenance	required	Who wrote the memory. Set by the server from the caller, never from the request body.
`playground`	boolean	required
`receipt_id`	string or null	required
`created_at`	string (date-time)	required
`updated_at`	string (date-time)	required

MemoryList

Field	Type		Notes
`data`	MemorySummary list	required
`next_cursor`	string or null	required	Pass as cursor for the next page. Null on the last page, and always null with page.

MemoryDeleted

Field	Type
`id`	string (uuid)	required
`deleted`	true	required
`receipt_id`	string	required

IngestJob

Field	Type		Notes
`job_id`	string (uuid)	required
`memory_id`	string (uuid)	required
`namespace_id`	string (uuid)	required
`stage`	one of: queued, extracting, chunking, embedding, indexing, done, failed	required
`stage_timestamps`	object	required
`failed_stage`	string or null	required
`failure_reason`	string or null	required
`attempts`	integer	required
`created_at`	string (date-time)	required
`updated_at`	string (date-time)	required
`stalled`	boolean	required	Not finished more than 4 hours after it was queued.
`terminal`	boolean	required	True at done or failed.
`poll_after_ms`	integer or null	required	How long to wait before polling again. Null when the job is terminal or stalled.

Namespace

Field	Type		Notes
`id`	string (uuid)	required
`name`	string, 1 to 64	required
`is_default`	boolean	required
`created_at`	string (date-time)	required
`updated_at`	string (date-time)	required
`memory_count`	integer		Only with include=stats on the list.
`last_activity_at`	string or null (date-time)		Only with include=stats on the list.

NamespaceList

Field	Type		Notes
`data`	Namespace list	required
`next_cursor`	string or null	required

KeyNamespaces

Field	Type		Notes
`key_id`	string	required
`data`	Namespace list	required

Provenance

Field	Type		Notes
`user_id`	string or null
`agent_id`	string or null
`app_id`	string or null
`run_id`	string or null

MemoryError

Field	Type		Notes
`error`	object	required