MESA Core · v0.9.3

HTTP API & Python SDK

v0.9.3 source: docs/api-reference.md

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#

MethodPathPurpose
GET/v4/capabilityOperational features and rebuild limits
POST / GET/v4/catalog/workspacesWorkspace catalog
POST / GET/v4/catalog/datasetsDataset catalog
POST / GET/v4/catalog/documentsDocument catalog
POST / GET/v4/catalog/revisionsImmutable revisions
POST/v4/catalog/source-chunksExact source chunks
POST/v4/sessions/startFreeze authorized dataset scope
POST/v4/memory/insertAdmit a durable chunk mutation (202)
POST/v4/documentsIngest a whole document with lossless chunking, duplicate detection and revision tracking (202)
POST/v4/memory/searchScoped hybrid retrieval
GET/v4/mutations/{mutation_id}Observe processing state
POST/v4/mutations/{mutation_id}/replayAuthorized retry
POST/v4/mutations/{mutation_id}/rollbackSource-owned rollback
GET/v4/sessions/{session_id}/contextBounded evidence context
POST/v4/sessions/{session_id}/endDurable 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.

Sections that moved to their own page
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.

CapabilityMeaning
canonical_ledger, projection_outbox, idempotent_ingestionDurable canonical work and projection contracts
vector_retrievalOperational embedding generation, not merely configured identity
lexical_retrieval, assertion_relational_laneSQLite lexical/assertion retrieval; not graph traversal
graph_projectionGraph projection availability
graph_neighbor_retrievalOperational neighbor retrieval implementation
validity_interval_filteringValidity filtering, not bitemporal semantics
durable_rebuildEnabled by MESA_V4_REBUILD_ENABLED; still offline and full-root
associative_ppr, bitemporal_query, human_reviewNot 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:

MethodPathSuccessPurpose
POST/v4/operations/rebuild202Submits a storage-root operation with a mandatory Idempotency-Key
GET/v4/operations/{operation_id}200Returns content-free state/progress
POST/v4/operations/{operation_id}/cancel200Cancels only a PENDING/RETRYABLE_FAILED operation
POST/v4/operations/{operation_id}/retry202Returns a safe RETRYABLE_FAILED checkpoint to pending
POST/v4/rebuild202Deprecated 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-rebuild-runbook.md`.

V4 catalog#

MethodPathRequired permissionPurpose
POST/v4/catalog/workspacesTenant OWNERCreates a tenant/workspace
GET/v4/catalog/workspacesREADER in the visible scopeLists workspaces
POST/v4/catalog/datasetsDataset/workspace OWNERCreates a dataset
GET/v4/catalog/datasetsREADER in the visible scopeLists datasets
POST/v4/catalog/documentsDataset WRITERCreates a document
GET/v4/catalog/documentsDataset READERLists documents
POST/v4/catalog/revisionsDataset WRITERCreates an immutable revision
GET/v4/catalog/revisionsDataset READERLists revisions
POST/v4/catalog/source-chunksDataset WRITERCreates an exact source chunk
DELETE/v4/catalog/documents/{document_id}Dataset OWNER + PURGEStarts 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

concepts and ingestion.

V4 session and memory#

MethodPathPurpose
POST/v4/sessions/startStarts a server-generated session whose dataset scope cannot change
POST/v4/memory/insertAdmits exact source and creates a mutation and pipeline run
POST/v4/memory/searchRuns 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}/replayRe-queues authorized DLQ/retry work
POST/v4/mutations/{mutation_id}/rollbackStarts a source-owned rollback
GET/v4/sessions/{session_id}/contextReturns session context and mutation provenance
POST/v4/sessions/{session_id}/endRequests 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.

python
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:

text
principal → tenant → workspace → dataset → agent → session

The 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_state summary with an API key
  • /health/init: public readiness; 200 {"status":"ready"} when ready, otherwise 503
  • /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:

json
{"error":"VALIDATION_ERROR","detail":"body.query: Input should be a valid string","status_code":422,"retryable":false}
ResponseNext step
401 UNAUTHORIZEDSupply the issued MESA key, not the provider key
403 ACCESS_DENIEDCheck tenant/dataset roles, agent grant and session scope
404 NOT_FOUNDCheck the ID and credential scope; hidden objects may also return 404
409 SESSION_INACTIVEStart an authorized active session before new writes
409 IDEMPOTENCY_CONFLICTReuse the original payload with that key, or use a new key for new content
422 VALIDATION_ERRORCorrect the named field/format; timestamps need a timezone
503 BACKEND_UNAVAILABLE, detail canonical_processing_unavailableRun one combined owner; non-combined profiles cannot ingest V4
503, detail vector_backend_unavailable / graph_backend_unavailableCheck provider credentials, embedding identity and backend readiness; an empty result is not a substitute
503, detail queue_over_capacity / maintenance_pendingRespect 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

configuration.

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.