Memory API

Memory is enabled per account by the platform, and the platform ties it to every task you submit. The caller names nothing: no namespace, no snapshot, no key. So there is no catalogue to drive from here — the whole customer-facing surface is one read-only route.

What you do need to know is whether the memory you were given is actually being applied to your tasks, and, when it is not, why. That is what this answers.

GET /api/builder/v1/memory/status

Same X-API-Key and X-Account-ID authentication as the rest of the Builder API. The account is the one the key belongs to; the call takes no parameters.

curl -s https://api.colabhive.com/api/builder/v1/memory/status \
  -H "X-API-Key: $COLABHIVE_API_KEY" \
  -H "X-Account-ID: $COLABHIVE_ACCOUNT_ID"

{ "enabled": true, "ready": false, "detail": "snapshot_pending" }

field	type	meaning
enabled	boolean	the platform enabled memory for this account
ready	boolean	a task submitted now would carry it
detail	string | null	why ready is false while enabled is true; null otherwise

Why enabled and ready are two fields

Because they fail apart. A namespace can exist and be authorised while there is still nothing to read from, or while its keys are still being provisioned. Collapsing them into one boolean would force the API to answer "no" to a question you did not ask — and leave you unable to tell "you do not have memory" from "you have it and it is not usable yet", which are different problems with different owners.

detail is a closed vocabulary

Never free text, so a client can branch on it:

value	meaning	who acts
snapshot_pending	memory is on, but the namespace has no snapshot to read from yet	wait — the first task that writes creates it
provisioning	the namespace keys are still being set up	wait
unavailable	the account's memory cannot be resolved	support has to look at it

Treat an unknown value as "not usable, reason I do not recognise" rather than an error: the list can grow, and a newer gateway must not break an older client.

Status codes

code	meaning
200	the status above. An account without memory is a 200 with enabled: false, not an error
401	no account context — the key was rejected or carries no account
404	this deployment does not serve the memory surface at all (a self-hosted install with memory off)

The distinction between 404 and enabled: false matters: the first says the platform has no memory feature here, the second says it has one and your account is not on it.

What this API does not do

There is no route to turn memory on, to create or name a namespace, to list namespaces, or to read or write what memory contains. The platform owns the binding and the caller names nothing — by construction, not as a gap waiting to be filled. A namespace belongs to one account and nothing reads across accounts; access is an explicit grant, and a revoked grant denies reads from that moment on.

If you need the model behind this, read Memory. The same answer is available from the SDK as client.memory.status() and from an MCP client as get_memory_status.