Agent protocol — API reference

Every operation of the agent protocol with its access level, parameters and response shape, rendered from the tool table and the OpenAPI document.

Generated by scripts/gen_skill_reference.py from docs/openapi/agent-protocol.json and the tool table. Do not edit by hand.

Base URL https://api.app.membase.io. Every request: Authorization: Bearer <developer key or consent token>. MCP endpoint https://api.app.membase.io/mcp-http (Streamable HTTP; the same tools by the same names).

Access levels

Level	Tools
Read (read)	list_containers, search_memories, get_profile, list_documents, get_document, memory_rules, ask_agent
Read & write (suggest)	list_containers, search_memories, get_profile, list_documents, get_document, memory_rules, ask_agent, add_memory, add_document
Full access (manage)	list_containers, search_memories, get_profile, list_documents, get_document, memory_rules, ask_agent, add_memory, add_document, delete_document, forget_memory
Invoke (invoke)	workflow_invoke

A level is the ceiling of what a credential of that kind may hold. A developer key holds every Read tool except ask_agent, which only an agent exposure (a marketplace subscription, a share) grants; get_profile is granted only when the owner ticked the profile on the key or on consent. A consent-minted client holds list_containers, search_memories and, when ticked, get_profile — nothing else: a verb outside a credential’s tools is not offered in tools/list and is refused with 403 when called.

Tools and endpoints

list_containers — List containers

level Read; read-only.

GET /v1/containers

The containers this credential may use — every one, for the account’s owner.

No parameters.

search_memories — Search memories

level Read; read-only.

POST /v1/search

Passages the containers hold on a question, most relevant first, each naming its container. Retrieval, not an answer — POST /v1/ask is the agent’s answer.

Field	Type	Required	Description
container	string	null	no
limit	integer	null	no
q	string	yes	The question, in natural language.

get_profile — Get the user’s profile

level Read; read-only.

GET /v1/profile

Who the user is: standing facts (static), the most recently changed facts (dynamic), and — with q — the passages relevant to the topic (results).

Field	Type	Required	Description
q (query)	string	null	no

list_documents — List documents

level Read; read-only.

GET /v1/documents

The documents the containers in reach have read, newest first.

Field	Type	Required	Description
container (query)	string	null	no

get_document — Get one document

level Read; read-only; REST only.

GET /v1/documents/{document_id}

One document, with whether its container has learned it yet.

Field	Type	Required	Description
document_id (path)	string	yes

memory_rules — Memory rules

level Read; read-only.

GET /v1/rules

The user’s standing rules for how their memory is used by this credential.

No parameters.

ask_agent — Ask the agent

level Read.

POST /v1/ask

Send a message to the agent this credential exposes and get its reply.

Field	Type	Required	Description
message	string	no
model	string	null	no

add_memory — Add a memory

level Read & write.

POST /v1/memories

Save one fact. Static facts go to the user’s profile; the rest to a container.

Field	Type	Required	Description
container	string	null	no
content	string	yes	The fact, as the user said it.
static	boolean	no	A standing fact about the user themselves.
title	string	no

add_document — Add a document

level Read & write.

POST /v1/documents

Hand a document (text or url) to a container. Lands at once; learned in the background — poll GET /v1/documents/{id} for learned.

Field	Type	Required	Description
container	string	yes	Which container reads it.
content	string	null	no
custom_id	string	no	Your own id; adding the same custom_id again is a no-op.
metadata	object	null	no
title	string	no
url	string	null	no

delete_document — Delete a document

level Full access; destructive — confirm=true from a developer key, or a request.

DELETE /v1/documents/{document_id}

Remove one document everywhere. Full access only: without confirm=true the answer is a request (status: confirmation_required); with it, a developer key deletes.

Field	Type	Required	Description
document_id (path)	string	yes
confirm (query)	boolean	no	Developer keys: true to delete.

forget_memory — Forget a memory

level Full access; destructive — confirm=true from a developer key, or a request.

DELETE /v1/memories/{memory_id}

Forget one learned fact. Same confirmation rule as deleting a document.

Field	Type	Required	Description
memory_id (path)	string	yes
container (query)	string	null	no
confirm (query)	boolean	no	Developer keys: true to forget.

workflow_invoke — Run the workflow

level Invoke.

MCP only: the workflow this credential exposes, with input as an object.

Retired names

Still answered for the credentials and clients that carry them; hidden from tools/list once the replacement is offered.

Retired	Current
memory_view_query	list_containers, search_memories
memory_list	list_containers
memory_recall	search_memories
memory_remember	add_memory
memory_ingest	add_document
memory_list_sources	list_documents
memory_forget	delete_document
agent_invoke	ask_agent

Errors

Status	Code	When
400	validation	an empty q; both or neither of content and url; container omitted when more than one is in reach
403	unauthorized	the container is outside the credential’s reach, or the verb above its access level
404	not_found	unknown document or memory
422	validation	a malformed body: a required field missing or of the wrong type
422	capability_unavailable	the account’s memory cannot run a turn here (no agent container, no model)
429	rate_limited	the account’s concurrent-turn budget, or too many requests on one credential

Read code, not only the status: 422 is either. A Full-access developer key calling a destructive verb without confirm=true answers 200 with {"status": "confirmation_required", "how": …} rather than an error.