Deployment info and health
One documented route tells you what a deployment is running before you send it work. Two more exist for operators of a self-hosted deployment: the liveness probe and the cost export. Base URL, authentication and error shapes are described in HTTP API conventions.
GET /deployment
Report the code revision, the model and document bindings, and the MCP memory tools the deployment is serving. It touches no submitted work, so you can call it first to confirm you are talking to the build you expect.
Scope: read.
Parameters
None.
Response
200 with a DeploymentBuildInfo:
{
"build_revision": "4e1d0c9a7b2f…",
"model_bindings": {
"claim_extraction": "…",
"p1_embedding": "…",
"fact_adjudication": "…"
},
"document_binding_generation": "…",
"tools": {
"ingest": 2,
"pipeline_readiness": 1,
"delete_document": 1,
"search_documents": 2,
"section_history": 1,
"document_references": 1,
"resolve_entity": 1,
"claims_and_sources_context": 3,
"facts_context": 3,
"combined_context": 4,
"query_sql": 1,
"…": 1
}
}| Field | Meaning |
|---|---|
build_revision | The source revision stamped into the image when it was built (REMEMBERSTACK_BUILD_REVISION). Empty when the image was built without one. |
model_bindings | The model each pipeline role is bound to, by role name. A self-hosted deployment reports structure_fallback, skeleton_check, section_role, section_summary, claim_extraction, relation_normalization, entity_resolution, fact_adjudication, p1_embedding (the one embedding model, used for every vector), and the OpenRouter settings openrouter_embedding_provider, openrouter_embedding_provider_order, openrouter_max_completion_tokens, openrouter_reasoning_effort and openrouter_reasoning_effort_map. No secrets. |
document_binding_generation | The deployment's current document binding generation, or null. |
tools | Each MCP memory tool this deployment serves, by tool name, with its tool version. A tool appears only when the route it calls is served: the seven query tools (query_sql, explain_sql, describe_query_space, search_query_space, list_saved_queries, describe_saved_query, run_saved_query) only when the open query space is enabled, delete_document only when document deletion is, search_documents |
only when document search is, and section_history and | |
document_references only when their routes are. A tool's version rises whenever a call it accepts would fail, or mean something else, on a deployment serving the previous version. |
The first three fields also appear on every
PipelineReadinessReport.
Errors
| Status | detail | Cause |
|---|---|---|
403 | credential may not perform this operation | The credential has the ingest scope, which cannot read. |
Example
curl -s "$REMEMBER_API_URL/deployment" \
-H "Authorization: Bearer $REMEMBER_API_KEY"GET /processing-layers
Report which processing layers the deployment processes and serves. The sources layer is always served and is not listed.
Scope: read.
Response
200 with an object holding one state per switchable layer:
{"claims": "enabled", "facts": "backfilling"}| State | Meaning |
|---|---|
enabled | Processed and served, with every live version processed. |
backfilling | Processed and served, while versions that missed the layer are still being processed. An empty answer that read it is a boundary, never known_empty. |
disabled | Neither processed nor served. Reads that need it are refused with 409 layer_unavailable. |
With the facts layer disabled, GET /operations, the tools of
GET /deployment and the MCP tool list leave out facts_context and
resolve_entity.
from remember import Client
memory = Client()
info = memory.deployment_build_info()
print(info.build_revision, info.model_bindings)GET /healthz
Note
Self-hosted only, and not part of the documented API: it is absent from
openapi.json.
Prove the engine process is up and can reach its PostgreSQL database. The Compose file uses it as the API container's health check.
Scope: none. This is the one route that never asks for a credential.
Response
200 with {"status": "ok"} after a SELECT 1 succeeds. If the database
cannot be reached, the request fails with 500. While a hard forget runs, it
answers 503 with {"detail": {"code": "forget_in_progress"}} like every
other route.
Example
curl -s http://localhost:8000/healthzGET /ops/cost-export/v1
Note
Self-hosted operators only. This route is served by a second, separate listener, not on the API's address, and only when you configure it.
Page through the deployment's cost receipts: one row per model call made by
the pipeline workers or by a query route, with tokens, cost and latency. It
never carries memory content. This is a resumable feed with its own contract
(outside the browse-list pagination rules):
every page echoes the request cursor, next_cursor stays set whenever the
batch has receipts, and stored cursors remain valid across deploys.
The listener starts only when REMEMBERSTACK_COST_EXPORT_BIND is set
(host:port, [ipv6]:port or unix:/path/to.sock). It then requires
REMEMBERSTACK_COST_EXPORT_TOKEN, at least 32 bytes long; the process refuses
to start without it. See Observability.
Authentication: Authorization: Bearer <REMEMBERSTACK_COST_EXPORT_TOKEN>.
This token is separate from the API credential.
Rate limit: one request per second, per process.
Parameters
| Name | In | Type | Required | Default | Constraints |
|---|---|---|---|---|---|
cursor | query | string | no | start | The next_cursor from the previous page. |
limit | query | integer | no | 100 | 1 to 500. |
Response
200 with a page:
| Field | Type | Meaning |
|---|---|---|
contract | string | Always rememberstack.cost_export.v1. |
deployment_id | UUID | |
server_time | date-time | When the page was read. |
horizon | date-time | The page covers receipts up to this instant. |
cursor | string | The cursor this page started from. |
next_cursor | string | Pass it back to continue. |
persist_failures | integer | Receipts the engine failed to record. |
scope_missing | integer | Receipts recorded without an attribution scope. |
receipts | array | The receipts, below. |
Each receipt:
| Field | Type |
|---|---|
cost_id | UUID |
deployment_id | UUID |
source | worker | surface |
work_id | UUID |
stage | string or null |
lane | string or null |
attempt | integer or null |
surface | string or null |
call_key | string |
outcome | string |
model_name | string or null |
tokens_in | integer or null |
tokens_out | integer or null |
cost_usd | decimal string or null |
latency_ms | integer or null |
occurred_at | date-time (UTC) |
Errors
| Status | detail | Cause |
|---|---|---|
401 | unauthorized | Missing or wrong token. |
422 | malformed cursor | The cursor does not parse. |
429 | rate limited | More than one request per second. |
Example
curl -s "http://127.0.0.1:8001/ops/cost-export/v1?limit=500" \
-H "Authorization: Bearer $REMEMBERSTACK_COST_EXPORT_TOKEN"