MESA Core · v0.9.3
HTTP API & Python SDK
This guide has equivalent English and Turkish versions. The source sections behind this page are at the bottom.
Authenticate and bind scope#
For every endpoint with request bodies, fields and response codes, see the HTTP endpoint reference.
Versioned memory, health and metrics requests require X-API-Key. Public /health/init, OpenAPI, Swagger and ReDoc need deployment network policy. Create catalog resources with an authorized principal before starting a dataset-bound session. The SDK example checks terminal state explicitly.
The implemented endpoint families#
| Method | Path | Purpose |
|---|---|---|
| GET | /v4/capability | Operational features and rebuild limits |
| POST / GET | /v4/catalog/workspaces | Workspace catalog |
| POST / GET | /v4/catalog/datasets | Dataset catalog |
| POST / GET | /v4/catalog/documents | Document catalog |
| POST / GET | /v4/catalog/revisions | Immutable revisions |
| POST | /v4/catalog/source-chunks | Exact source chunks |
| POST | /v4/sessions/start | Freeze authorized dataset scope |
| POST | /v4/memory/insert | Admit a durable chunk mutation (202) |
| POST | /v4/documents | Ingest a whole document with lossless chunking, duplicate detection and revision tracking (202) |
| POST | /v4/memory/search | Scoped hybrid retrieval |
| GET | /v4/mutations/{mutation_id} | Observe processing state |
| POST | /v4/mutations/{mutation_id}/replay | Authorized retry |
| POST | /v4/mutations/{mutation_id}/rollback | Source-owned rollback |
| GET | /v4/sessions/{session_id}/context | Bounded evidence context |
| POST | /v4/sessions/{session_id}/end | Durable session finalization |
Response and error contracts#
202 means admission. A successful write must reach COMMITTED. Search exposes rrf_score, legal_factor, raw_score, final_score and contributing origins. Model-disabled combined operation accepts documents and supports BM25 search; disabled VECTOR lanes are SKIPPED. 503 canonical_processing_unavailable means the combined consumer is unavailable. Search reports missing lanes in degraded_sources; expected provider failures are explicit 503 responses. Administrative rebuild is separate and disabled by default. The pinned appendix contains request schemas, remaining administrative endpoints and authorization details.
Whole-document ingestion#
POST /v4/documents accepts session_id, dataset_id, document_id, title, source_ref, content and optional metadata. The response includes revision_id, revision_number, chunk_count, mutation_ids and duplicate. Poll every mutation for COMMITTED. Identical ACTIVE content reuses its IDs; changed content creates a revision. Text is limited to 5,000,000 UTF-8 bytes; blank text returns 422 and purged document IDs cannot be reused. Mesa().add() uses this endpoint.
- CLI commands → CLI reference
- MCP control API →
Source reference for this page
The sections of the upstream file that back this page, translated to English where the original mixes in Turkish. The GitHub link shows the exact original.
MESA exposes the V4 tenant/dataset-authorized API. This English source copy follows the v0.9.3 V4 contracts; the website release notes record verified GitHub and PyPI publication. Production qualification remains separate.
Versioned memory, health and metrics calls require X-API-Key. /health/init, OpenAPI, Swagger and ReDoc are public surfaces and need a network/reverse-proxy policy. The V4 key is
generated with mesa-v4-admin issue-key; only a salted scrypt hash is stored.
The working source of the OpenAPI contract is mesa_api/v4_router.py.
V4 capability#
GET /v4/capability returns api_version, features, capabilities and
limits. features contains the capability names whose values are true.
The response depends on the configured and operational runtime; a sample
response must not be used as a fixed feature promise.
| Capability | Meaning |
|---|---|
canonical_ledger, projection_outbox, idempotent_ingestion | Durable canonical work and projection contracts |
vector_retrieval | Operational embedding generation, not merely configured identity |
lexical_retrieval, assertion_relational_lane | SQLite lexical/assertion retrieval; not graph traversal |
graph_projection | Graph projection availability |
graph_neighbor_retrieval | Operational neighbor retrieval implementation |
validity_interval_filtering | Validity filtering, not bitemporal semantics |
durable_rebuild | Enabled by MESA_V4_REBUILD_ENABLED; still offline and full-root |
associative_ppr, bitemporal_query, human_review | Not advertised as implemented Core capabilities |
Rebuild limits are rebuild_kind=projection, rebuild_scope=storage_root, and
requires_offline_runner=true. A projection-only graph adapter does not supply
neighbor retrieval. Custom embedding providers are non-operational until a
successful embedding call. Configured backend failure is surfaced explicitly;
see retrieval behavior and troubleshooting.
V4 administrative rebuild operations#
This surface is only for a control-plane ADMIN principal and accepts no
physical path or canonical content:
| Method | Path | Success | Purpose |
|---|---|---|---|
POST | /v4/operations/rebuild | 202 | Submits a storage-root operation with a mandatory Idempotency-Key |
GET | /v4/operations/{operation_id} | 200 | Returns content-free state/progress |
POST | /v4/operations/{operation_id}/cancel | 200 | Cancels only a PENDING/RETRYABLE_FAILED operation |
POST | /v4/operations/{operation_id}/retry | 202 | Returns a safe RETRYABLE_FAILED checkpoint to pending |
POST | /v4/rebuild | 202 | Deprecated storage-root alias |
With the flag off, submit/retry returns 501; an unsupported scoped alias returns 409;
an invalid state returns 409. Unauthorized status/cancel/retry returns 404 so the
operation's existence is not leaked. The state flow is
PENDING → CLAIMED → RUNNING → VERIFYING → READY_TO_CUTOVER → COMPLETED;
side states are RETRYABLE_FAILED, FINAL_FAILED and CANCELLED. While an
operation is active or retryable, mutation admission returns 503 maintenance_pending.
The offline operating procedure is in
V4 catalog#
| Method | Path | Required permission | Purpose |
|---|---|---|---|
POST | /v4/catalog/workspaces | Tenant OWNER | Creates a tenant/workspace |
GET | /v4/catalog/workspaces | READER in the visible scope | Lists workspaces |
POST | /v4/catalog/datasets | Dataset/workspace OWNER | Creates a dataset |
GET | /v4/catalog/datasets | READER in the visible scope | Lists datasets |
POST | /v4/catalog/documents | Dataset WRITER | Creates a document |
GET | /v4/catalog/documents | Dataset READER | Lists documents |
POST | /v4/catalog/revisions | Dataset WRITER | Creates an immutable revision |
GET | /v4/catalog/revisions | Dataset READER | Lists revisions |
POST | /v4/catalog/source-chunks | Dataset WRITER | Creates an exact source chunk |
DELETE | /v4/catalog/documents/{document_id} | Dataset OWNER + PURGE | Starts a source-owned purge |
Document purge erases source and extracted text while retaining identifiers and hashes; shared text remains while another document still owns it.
Catalog IDs are tenant-scoped public IDs; physical storage keys are not public
aliases. Revision/chunk identity, finalization and the distinction between
declared_content_hash, manifest_hash and chunk content_hash are defined in
V4 session and memory#
| Method | Path | Purpose |
|---|---|---|
POST | /v4/sessions/start | Starts a server-generated session whose dataset scope cannot change |
POST | /v4/memory/insert | Admits exact source and creates a mutation and pipeline run |
POST | /v4/memory/search | Runs vector/BM25/assertion/graph RRF search over authorized datasets |
GET | /v4/mutations/{mutation_id} | Returns state, pipeline, artifact and projection status |
POST | /v4/mutations/{mutation_id}/replay | Re-queues authorized DLQ/retry work |
POST | /v4/mutations/{mutation_id}/rollback | Starts a source-owned rollback |
GET | /v4/sessions/{session_id}/context | Returns session context and mutation provenance |
POST | /v4/sessions/{session_id}/end | Requests durable finalization and closes the session |
Insert derives tenant/workspace/agent from the authorized session and returns
202 with mutation_id, candidate_id, pipeline_run_id and raw_log_id.
This is admission; poll status and require COMMITTED before assuming success.
wait_until_committed() also returns failed terminal states.
For multiple chunks use distinct IDs/ordinals, finalize_revision=false until
the last insert, then true. Retry the exact payload with the same body
idempotency_key. Revision lifecycle, rejection/replay and rollback semantics
are defined in concepts and ingestion.
The HTTP insert contract accepts optional typed legal_identity: law_id and
article_id are required within that object; statute_code, version_id,
paragraph_id and clause_id are optional. Identity must resolve consistently
through the bounded legal aliases. Caller metadata cannot supply trusted
_mesa_* fields. The producer remains responsible for source truth.
Search includes degraded_sources: vector when embeddings are off or any scoped committed record has an incomplete VECTOR lane; graph for incomplete/disabled GRAPH lanes. Otherwise it is empty.
Search and context both accept jurisdiction, valid_at, valid_from and
valid_to. Context uses query parameters and defaults to token_budget=2048,
retrieval_mode=single. Opt-in adaptive permits at most one planner call and
two additional scoped searches. Scores, graph provenance, proof packing and
offline token counting are defined in retrieval and graph.
Raw /v4/memory/search remains the single-query primitive.
V4 Python SDK#
This example assumes a model-enabled V4 server, a provisioned credential, an existing
tenant-a/workspace-a/dataset-a catalog and session permission for agent-a.
For an example that also sets these up, use Getting started.
from mesa_client import MesaV4Client
with MesaV4Client("http://127.0.0.1:8000", api_key=credential) as client:
session = client.start_session(
tenant_id="tenant-a",
workspace_id="workspace-a",
dataset_ids=["dataset-a"],
agent_id="agent-a",
)
accepted = client.insert(
session_id=session["session_id"],
dataset_id="dataset-a",
document_id="doc-a",
revision_id="rev-1",
chunk_id="chunk-1",
title="Neutral source example",
source_ref="demo://source-a",
content="Exact source text",
)
terminal = client.wait_until_committed(accepted["mutation_id"])
if terminal["state"] != "COMMITTED":
raise RuntimeError(terminal["state"])
result = client.search(session_id=session["session_id"], query="Exact source")
for hit in result["results"]:
print(hit["assertion_id"])
for source in hit.get("provenance", []):
print(source["source_ref"], source["dataset_id"], source["chunk_id"])
context = client.get_context(session_id=session["session_id"], query="Exact source")
print(context["context"])
client.end_session(session_id=session["session_id"])accepted is durable admission, not finished retrieval. client.status(mutation_id)
exposes state, failure_class, rejection_reason, pipeline_run, artifacts
and projections. Wait for COMMITTED; REJECTED, DEAD_LETTER, BLOCKED and
ROLLED_BACK are terminal outcomes too. A wait timeout raises MesaNetworkError
and leaves the mutation running. Recheck status; for an uncertain insert retry
the same payload with an explicit, unchanged idempotency_key.
results=[] on a successful search means no matching visible evidence. Provider,
storage and authorization failures raise errors instead. Each hit's
assertion_id identifies a canonical claim; provenance links it to the source
and dataset/chunk. A score ranks evidence; it is not a truth probability.
Context returns packed text in context and structured evidence in
canonical_memories; mutations contains bounded ID/state receipts without raw evidence spans. Finish retrieval before end_session; closing the HTTP
client alone does not end the server session.
For async code use async with AsyncMesaV4Client(...) as client and await each
of these methods, including polling and end_session. Do not run the blocking
MesaV4Client inside an event loop. Async clients also support await client.aclose();
sync clients support client.close().
For a multi-chunk revision, use finalize_revision=False on the first calls and the
default True on the last call. The search and get_context methods
support all three of valid_at, valid_from and valid_to.
Besides capability, catalog, session, insert, search, status, wait, replay,
rollback, purge, context and end operations, MesaV4Client and AsyncMesaV4Client
offer the control-plane methods submit_rebuild, operation_status,
cancel_operation and retry_operation. The V3 clients are kept as MesaClient
and AsyncMesaClient. The dataset-bound MCP surface offers no mutating global
rebuild tool.
V4 authorization#
The route layer resolves this context on the server:
principal → tenant → workspace → dataset → agent → sessionThe OWNER, WRITER and READER roles inherit downward. Purge and
rollback additionally need the dataset PURGE or ROLLBACK permission. An agent is a
persona/compute context; on its own it is not a security boundary.
Rollback and replay are historical management operations; the originating session may
be closed. Even so, principal/session ownership, the match between the mutation's and
the session's tenant/workspace/dataset/agent scope, the dataset role and the explicit
ROLLBACK permission are verified on every call.
Provision keys, roles and explicit dataset permissions using the
operations runbook; the
CLI reference identifies admin entry points. RBAC uses its
own schema version in the policy database, independently of Alembic migrations
for canonical storage. Lost grants from an old database cannot be inferred or
recreated automatically.
Internal DAO ownership, projection and Graph V2 structure belong in the
architecture; they are not separate public HTTP methods.
Health and metrics#
/health:status,maintenance,rebuild_statesummary with an API key/health/init: public readiness;200 {"status":"ready"}when ready, otherwise503/metrics: Prometheus counters and gauges with an API key
/health can return HTTP 200 even when degraded or in maintenance; do not treat the
HTTP code alone as success — check the status field. Detailed queue,
projection and rebuild counters are read from /metrics.
V4 metrics cover projection backlog/DLQ/stuck leases, cleanup backlog/BLOCKED,
ownerless registry, shared artifacts and rebuild state/duration/progress,
parity-missing, staging bytes and rollback counts. Alert rules are in
docs/prometheus_alerts.yml.
Request and SDK details#
title is required for V4 HTTP insert and the sync/async SDK insert. title is 1..512,
content 1..32768 characters, source_ref 1..2048, evidence_span at most 4096 and
idempotency_key at most 128 characters. The dataset must belong to the session.
HTTP and the sync/async SDK insert support the optional legal_identity parameter.
Use the running OpenAPI for differences between public/source ID validators.
A search request requires session_id and query; the query is 1..4096 characters,
limit defaults to 10 within 1..50, dataset_ids, when given, is 1..64 and a subset of the
session, and graph_mode is enabled/disabled. ISO timestamp strings must include a
timezone offset. valid_from > valid_to is rejected. The response carries session_id,
dataset_ids, results and optional scope_audit, graph_ablation and vector_lane.
The presence of result provenance does not guarantee source truth.
The SDK sync/async client defaults to a 10 s timeout and max_retries 3; only the safe
network retry boundary applies. API HTTP error responses become MesaAPIError,
network errors MesaNetworkError, SDK schema errors MesaValidationError. Status
400/401/403/404/409/413/422/429/503 varies by endpoint; OpenAPI and the contract
tests are the source of authority. Honour Retry-After for queue saturation and rebuild
maintenance. Per-minute (60/minute) and daily (10000) limits are not enforced for /v4/* and /control/* in v0.9.3.
Whole documents: POST /v4/documents#
Send session_id, dataset_id, document_id, title, source_ref, content
and optional metadata. The session requires WRITE access to the dataset and
the runtime must own the combined consumer, just as for /v4/memory/insert.
With MESA_CHUNKING=auto (default), at least three line-start Turkish article headings preserve article boundaries. Long pieces remain at most 512 cl100k tokens; plain uses paragraph, sentence and hard-cut splitting. Joining the slices
reproduces the input exactly, including whitespace.
HTTP 202 returns document_id, revision_id, revision_number, chunk_count,
mutation_ids and duplicate. It means admission; poll each mutation until
COMMITTED before relying on the new revision in search. A changed document
gets the next revision number and supersedes the active revision when all its
chunks commit. Repeating the same document and content returns its existing IDs
with duplicate: true for an ACTIVE revision, using its stored chunk count and
mutation IDs without rechunking. Retrying an interrupted PENDING upload resumes
its missing chunks with the plan matching admitted text; an ambiguous prefix matching two plans returns HTTP 409 without appending. Existing ACTIVE revisions are unchanged. Other matching revisions return 409 `content equals revision
<n> (<status>); restoring an earlier revision is not supported in v0.9`.
Revision IDs are rev- plus the first 32 hex characters of
sha256(document_id + "\n" + sha256(content)), with the inner hash represented
as lowercase hex and strings encoded as UTF-8. Chunk IDs append -c and a
zero-based five-digit ordinal. Per-chunk idempotency keys are these chunk IDs.
Errors: 409 document is purged; 413 for content over 5,000,000 UTF-8 bytes;
422 for empty or whitespace-only content. Secrets and metadata use the same
validation and errors as /v4/memory/insert. Queue and maintenance failures
use the existing admission errors below.
Actionable errors#
Catch MesaAPIError to inspect status_code, error and detail. HTTP bodies
also include retryable; the SDK does not automatically retry HTTP failures.
Rejected request values and internal route paths are omitted from validation
errors. For example, a non-string search query returns HTTP 422:
{"error":"VALIDATION_ERROR","detail":"body.query: Input should be a valid string","status_code":422,"retryable":false}| Response | Next step |
|---|---|
401 UNAUTHORIZED | Supply the issued MESA key, not the provider key |
403 ACCESS_DENIED | Check tenant/dataset roles, agent grant and session scope |
404 NOT_FOUND | Check the ID and credential scope; hidden objects may also return 404 |
409 SESSION_INACTIVE | Start an authorized active session before new writes |
409 IDEMPOTENCY_CONFLICT | Reuse the original payload with that key, or use a new key for new content |
422 VALIDATION_ERROR | Correct the named field/format; timestamps need a timezone |
503 BACKEND_UNAVAILABLE, detail canonical_processing_unavailable | Run one combined owner; non-combined profiles cannot ingest V4 |
503, detail vector_backend_unavailable / graph_backend_unavailable | Check provider credentials, embedding identity and backend readiness; an empty result is not a substitute |
503, detail queue_over_capacity / maintenance_pending | Respect Retry-After when present and wait for capacity/maintenance |
Failed background processing is reported by mutation status even when the insert
returned 202. Inspect its failure/projection fields; an admission response or an
empty early search does not establish successful processing. Startup
configuration errors appear in the server terminal before readiness; see
The list catalog calls offer no explicitly documented pagination guarantee here;
inspect the response/schema. A runnable example, including the first catalog/ACL and
credential prerequisites, is in Getting started.
Canonical V4 insertion requires the combined processing consumer. With models off, records have a SKIPPED VECTOR lane and remain searchable through BM25. Enabling embeddings later backfills skipped lanes without hiding committed records.
The OpenAPI snapshot is a generated reference.
Use the running app's /openapi.json and route/schema source for the exact
checkout; do not infer snapshot freshness from this page. Generating a schema
without server startup does not exercise authentication or runtime behavior.
v0.9.1 SDK and CLI additions#
mesa add waits for ACTIVE by default (--no-wait returns admission); Mesa.add(text, source=..., wait=True) explicitly waits because its tagged SDK default is wait=False. Terminal chunk errors include mutation ID, state and error class; RETRY_PENDING remains pending. Delete with mesa delete --source <ref> or Mesa.delete(source=...); document IDs remain supported. Optional [ml] BGE reranking adds rerank_score without replacing fusion fields. V4 HTTP routes and request shapes remain compatible.
