MESA Core · v0.9.3

HTTP endpoint reference

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.

Overview#

Generated from the OpenAPI document published with Core v0.9.3 (commit 531209b). Example bodies are built from the schema to show the shape of a request; they are not recorded server responses.

Every endpoint except /health/init needs the X-API-Key header. What a V4 call may touch is limited by the roles granted to that key; see Security & Scope.

Download the OpenAPI JSON

V4 · memory, catalog and sessions#

POST /v4/catalog/workspaces#

Create Workspace · Requires X-API-Key.

Request body · V4WorkspaceRequest

json
{
  "tenant_id": "docs-tenant",
  "workspace_id": "docs-workspace"
}
FieldTypeRequiredDescription
tenant_idstringyes
workspace_idstringyes
tenant_namestring \nullno
workspace_namestring \nullno

Responses

  • 201 Successful Response
  • 422 Validation Error · HTTPValidationError

GET /v4/catalog/workspaces#

List Workspaces · Requires X-API-Key.

Parameters

NameInTypeRequired
tenant_idquerystringyes

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

POST /v4/catalog/datasets#

Create Dataset · Requires X-API-Key.

Request body · V4DatasetRequest

json
{
  "tenant_id": "docs-tenant",
  "workspace_id": "docs-workspace",
  "dataset_id": "docs-dataset"
}
FieldTypeRequiredDescription
tenant_idstringyes
workspace_idstringyes
dataset_idstringyes
tenant_namestring \nullno
workspace_namestring \nullno
dataset_namestring \nullno

Responses

  • 201 Successful Response
  • 422 Validation Error · HTTPValidationError

GET /v4/catalog/datasets#

List Datasets · Requires X-API-Key.

Parameters

NameInTypeRequired
tenant_idquerystringyes
workspace_idquerystringyes

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

POST /v4/catalog/documents#

Create Document · Requires X-API-Key.

Request body · V4DocumentRequest

json
{
  "tenant_id": "docs-tenant",
  "workspace_id": "docs-workspace",
  "dataset_id": "docs-dataset",
  "document_id": "archive-hours",
  "title": "Archive opening hours"
}
FieldTypeRequiredDescription
tenant_idstringyes
workspace_idstringyes
dataset_idstringyes
document_idstringyes
titlestringyes
external_refstring \nullno

Responses

  • 201 Successful Response
  • 422 Validation Error · HTTPValidationError

GET /v4/catalog/documents#

List Documents · Requires X-API-Key.

Parameters

NameInTypeRequired
tenant_idquerystringyes
workspace_idquerystringyes
dataset_idquerystringyes

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

POST /v4/catalog/revisions#

Create Revision · Requires X-API-Key.

Request body · V4RevisionRequest

json
{
  "tenant_id": "docs-tenant",
  "workspace_id": "docs-workspace",
  "dataset_id": "docs-dataset",
  "document_id": "archive-hours",
  "revision_id": "revision-1",
  "revision_number": 1,
  "content_sha256": "string"
}
FieldTypeRequiredDescription
tenant_idstringyes
workspace_idstringyes
dataset_idstringyes
document_idstringyes
revision_idstringyes
revision_numberintegeryes
content_sha256stringyes
supersedes_revision_idstring \nullno

Responses

  • 201 Successful Response
  • 422 Validation Error · HTTPValidationError

GET /v4/catalog/revisions#

List Revisions · Requires X-API-Key.

Parameters

NameInTypeRequired
tenant_idquerystringyes
workspace_idquerystringyes
dataset_idquerystringyes
document_idquerystringyes

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

POST /v4/catalog/source-chunks#

Create Source Chunk · Requires X-API-Key.

Request body · V4SourceChunkRequest

json
{
  "tenant_id": "docs-tenant",
  "workspace_id": "docs-workspace",
  "dataset_id": "docs-dataset",
  "document_id": "archive-hours",
  "revision_id": "revision-1",
  "chunk_id": "chunk-1",
  "title": "Archive opening hours",
  "content": "The archive opens at nine on weekdays.",
  "source_ref": "demo://archive-hours"
}
FieldTypeRequiredDescription
tenant_idstringyes
workspace_idstringyes
dataset_idstringyes
document_idstringyes
revision_idstringyes
chunk_idstringyes
titlestringyes
contentstringyes
source_refstringyes
revision_numberintegerno
chunk_ordinalintegerno
finalize_revisionbooleanno
external_refstring \nullno
supersedes_revision_idstring \nullno

Responses

  • 201 Successful Response
  • 422 Validation Error · HTTPValidationError

DELETE /v4/catalog/documents/{document_id}#

Purge Document · Requires X-API-Key.

Parameters

NameInTypeRequired
document_idpathstringyes
tenant_idquerystringyes
workspace_idquerystringyes
dataset_idquerystringyes

Responses

  • 202 Successful Response
  • 422 Validation Error · HTTPValidationError

POST /v4/sessions/start#

Start Session · Requires X-API-Key.

Request body · V4SessionStartRequest

json
{
  "tenant_id": "docs-tenant",
  "workspace_id": "docs-workspace",
  "dataset_ids": [
    "string"
  ],
  "agent_id": "docs-agent"
}
FieldTypeRequiredDescription
tenant_idstringyes
workspace_idstringyes
dataset_idsarray<string>yes
agent_idstringyes

Responses

  • 201 Successful Response
  • 422 Validation Error · HTTPValidationError

GET /v4/capability#

Get Capability · Requires X-API-Key.

Responses

  • 200 Successful Response · V4CapabilityResponse

Example

json
{
  "api_version": "v4",
  "features": [
    "string"
  ],
  "capabilities": {
    "canonical_ledger": true,
    "projection_outbox": true,
    "idempotent_ingestion": true,
    "vector_retrieval": true,
    "lexical_retrieval": true,
    "assertion_relational_lane": true
  },
  "validation": {
    "mode": 0,
    "policy": "deterministic_only",
    "llm_validation_enabled": false,
    "validator_count": 0
  },
  "limits": {
    "rebuild_kind": "projection",
    "rebuild_scope": "storage_root",
    "requires_offline_runner": true
  }
}

POST /v4/operations/rebuild#

Create Rebuild Operation · Requires X-API-Key.

Parameters

NameInTypeRequired
Idempotency-Keyheaderstringyes

Responses

  • 202 Successful Response · V4OperationResponse
  • 422 Validation Error · HTTPValidationError

Example

json
{
  "operation_id": "<operation_id>",
  "operation_kind": "projection_rebuild",
  "scope": "storage_root",
  "state": "string",
  "attempt": 0,
  "progress": {
    "completed": 0,
    "total": 0
  }
}

GET /v4/operations/{operation_id}#

Get Rebuild Operation · Requires X-API-Key.

Parameters

NameInTypeRequired
operation_idpathstringyes

Responses

  • 200 Successful Response · V4OperationResponse
  • 422 Validation Error · HTTPValidationError

Example

json
{
  "operation_id": "<operation_id>",
  "operation_kind": "projection_rebuild",
  "scope": "storage_root",
  "state": "string",
  "attempt": 0,
  "progress": {
    "completed": 0,
    "total": 0
  }
}

POST /v4/operations/{operation_id}/cancel#

Cancel Rebuild Operation · Requires X-API-Key.

Parameters

NameInTypeRequired
operation_idpathstringyes

Responses

  • 200 Successful Response · V4OperationResponse
  • 422 Validation Error · HTTPValidationError

Example

json
{
  "operation_id": "<operation_id>",
  "operation_kind": "projection_rebuild",
  "scope": "storage_root",
  "state": "string",
  "attempt": 0,
  "progress": {
    "completed": 0,
    "total": 0
  }
}

POST /v4/operations/{operation_id}/retry#

Retry Rebuild Operation · Requires X-API-Key.

Parameters

NameInTypeRequired
operation_idpathstringyes

Responses

  • 202 Successful Response · V4OperationResponse
  • 422 Validation Error · HTTPValidationError

Example

json
{
  "operation_id": "<operation_id>",
  "operation_kind": "projection_rebuild",
  "scope": "storage_root",
  "state": "string",
  "attempt": 0,
  "progress": {
    "completed": 0,
    "total": 0
  }
}

POST /v4/rebuild#

Rebuild Index · Requires X-API-Key.

Parameters

NameInTypeRequired
tenant_idquerystring \nullno
workspace_idquerystring \nullno
dataset_idquerystring \nullno
Idempotency-Keyheaderstringyes

Responses

  • 202 Successful Response · V4OperationResponse
  • 422 Validation Error · HTTPValidationError

Example

json
{
  "operation_id": "<operation_id>",
  "operation_kind": "projection_rebuild",
  "scope": "storage_root",
  "state": "string",
  "attempt": 0,
  "progress": {
    "completed": 0,
    "total": 0
  }
}

POST /v4/memory/insert#

Insert Memory · Requires X-API-Key.

Request body · V4MemoryInsertRequest

json
{
  "session_id": "<session_id>",
  "dataset_id": "docs-dataset",
  "document_id": "archive-hours",
  "revision_id": "revision-1",
  "chunk_id": "chunk-1",
  "title": "Archive opening hours",
  "source_ref": "demo://archive-hours",
  "content": "The archive opens at nine on weekdays."
}
FieldTypeRequiredDescription
session_idstringyes
dataset_idstringyes
document_idstringyes
revision_idstringyes
chunk_idstringyes
titlestringyes
source_refstringyes
contentstringyes
evidence_spanstringno
revision_numberintegerno
chunk_ordinalintegerno
finalize_revisionbooleanno
supersedes_revision_idstring \nullno
metadataobjectno
legal_identityV4LegalIdentityRequest \nullno
idempotency_keystring \nullno

Responses

  • 202 Successful Response
  • 422 Validation Error · HTTPValidationError

POST /v4/documents#

Ingest Document · Requires X-API-Key.

Request body · V4DocumentIngestRequest

json
{
  "session_id": "<session_id>",
  "dataset_id": "docs-dataset",
  "document_id": "archive-hours",
  "title": "Archive opening hours",
  "source_ref": "demo://archive-hours",
  "content": "The archive opens at nine on weekdays."
}
FieldTypeRequiredDescription
session_idstringyes
dataset_idstringyes
document_idstringyes
titlestringyes
source_refstringyes
contentstringyes
metadataobjectno

Responses

  • 202 Successful Response · V4DocumentIngestResponse
  • 422 Validation Error · HTTPValidationError

Example

json
{
  "document_id": "archive-hours",
  "revision_id": "revision-1",
  "revision_number": 1,
  "chunk_count": 1,
  "mutation_ids": [
    "string"
  ],
  "duplicate": true
}

POST /v4/memory/search#

Search Memory · Requires X-API-Key.

Request body · V4SearchRequest

json
{
  "session_id": "<session_id>",
  "query": "When does the archive open?"
}
FieldTypeRequiredDescription
session_idstringyes
dataset_idsarray<string> \nullno
querystringyes
limitintegerno
jurisdictionstring \nullno
valid_atstring \nullno
valid_fromstring \nullno
valid_tostring \nullno
graph_modeenabled · disablednoEnable or disable only the graph retrieval lane for matched ablation.

Responses

  • 200 Successful Response · V4SearchResponse
  • 422 Validation Error · HTTPValidationError

Example

json
{
  "session_id": "<session_id>",
  "dataset_ids": [
    "string"
  ],
  "results": [
    {}
  ],
  "degraded_sources": [],
  "scope_audit": {
    "contract_version": "string",
    "enforcement_stage": "string",
    "requested_scope": {},
    "requested_scope_identity": "string",
    "query_identity": "string",
    "evaluated_candidate_count": 0
  },
  "graph_ablation": {
    "contract_version": "string",
    "mode": "enabled",
    "pair_identity": "string",
    "query_identity": "string",
    "retrieval_config_identity": "string",
    "scope_identity": "string"
  }
}

GET /v4/mutations/{mutation_id}#

Mutation Status · Requires X-API-Key.

Parameters

NameInTypeRequired
mutation_idpathstringyes

Responses

  • 200 Successful Response · V4MutationStatusResponse
  • 422 Validation Error · HTTPValidationError

Example

json
{
  "mutation_id": "<mutation_id>",
  "candidate_id": "string",
  "state": "string",
  "failure_class": "string",
  "rejection_reason": "string",
  "tier3_audit": {}
}

POST /v4/mutations/{mutation_id}/rollback#

Rollback Mutation · Requires X-API-Key.

Parameters

NameInTypeRequired
mutation_idpathstringyes

Responses

  • 202 Successful Response
  • 422 Validation Error · HTTPValidationError

POST /v4/mutations/{mutation_id}/replay#

Replay Mutation · Requires X-API-Key.

Parameters

NameInTypeRequired
mutation_idpathstringyes

Responses

  • 202 Successful Response
  • 422 Validation Error · HTTPValidationError

GET /v4/sessions/{session_id}/context#

Get Context · Requires X-API-Key.

Parameters

NameInTypeRequired
session_idpathstringyes
queryquerystringno
token_budgetqueryintegerno
jurisdictionquerystring \nullno
valid_atquerystring \nullno
valid_fromquerystring \nullno
valid_toquerystring \nullno
retrieval_modequerysingle · adaptiveno

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

POST /v4/sessions/{session_id}/end#

End Session · Requires X-API-Key.

Parameters

NameInTypeRequired
session_idpathstringyes

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

Health and metrics#

GET /health/init#

Health Init · No API key required.

Responses

  • 200 Successful Response

GET /health#

Health · Requires X-API-Key.

Responses

  • 200 Successful Response

GET /metrics#

Metrics · Requires X-API-Key.

Responses

  • 200 Successful Response

MCP control plane#

GET /control/mcp/clients#

List Clients · Requires X-API-Key.

Responses

  • 200 Successful Response

POST /control/mcp/clients#

Create Client · Requires X-API-Key.

Request body · ClientCreateReq

json
{
  "client_id": "string",
  "display_name": "string",
  "client_type": "string",
  "principal_id": "string"
}
FieldTypeRequiredDescription
client_idstringyes
display_namestringyes
client_typestringyes
principal_idstringyes
metadataobjectno

Responses

  • 201 Successful Response
  • 422 Validation Error · HTTPValidationError

GET /control/mcp/clients/{client_id}#

Get Client · Requires X-API-Key.

Parameters

NameInTypeRequired
client_idpathstringyes

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

GET /control/mcp/connections#

List Connections · Requires X-API-Key.

Parameters

NameInTypeRequired
client_idquerystring \nullno

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

GET /control/mcp/settings#

Get Settings · Requires X-API-Key.

Responses

  • 200 Successful Response

POST /control/mcp/settings#

Update Setting · Requires X-API-Key.

Parameters

NameInTypeRequired
keyquerystringyes
valuequeryobjectyes

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

POST /control/mcp/policies#

Create Policy · Requires X-API-Key.

Request body · PolicyCreateReq

json
{
  "rule_id": "string",
  "scope_type": "string",
  "operation": "string",
  "effect": "string",
  "created_by": "string"
}
FieldTypeRequiredDescription
rule_idstringyes
scope_typestringyes
operationstringyes
effectstringyes
created_bystringyes
scope_idstring \nullno
priorityintegerno
conditionsobjectno

Responses

  • 201 Successful Response
  • 422 Validation Error · HTTPValidationError

GET /control/mcp/policies#

List Policies · Requires X-API-Key.

Parameters

NameInTypeRequired
operationquerystring \nullno

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

PUT /control/mcp/clients/{client_id}/enabled#

Toggle Client Enabled · Requires X-API-Key.

Parameters

NameInTypeRequired
client_idpathstringyes
enabledquerybooleanyes

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

GET /control/mcp/clients/{client_id}/bindings#

List Bindings · Requires X-API-Key.

Parameters

NameInTypeRequired
client_idpathstringyes

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

GET /control/mcp/managed-clients#

List Managed Clients · Requires X-API-Key.

Responses

  • 200 Successful Response

POST /control/mcp/credentials/{credential_id}/revoke#

Revoke Managed Credential · Requires X-API-Key.

Parameters

NameInTypeRequired
credential_idpathstringyes

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

GET /control/mcp/activity#

List Activity · Requires X-API-Key.

Parameters

NameInTypeRequired
limitqueryintegerno
offsetqueryintegerno
client_idquerystring \nullno
statusquerystring \nullno

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

GET /control/mcp/activity/{call_id}#

Get Activity Call · Requires X-API-Key.

Parameters

NameInTypeRequired
call_idpathstringyes

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

GET /control/mcp/approvals#

List Approvals · Requires X-API-Key.

Parameters

NameInTypeRequired
statusquerystring \nullno
limitqueryintegerno
offsetqueryintegerno

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

GET /control/mcp/approvals/pending#

List Pending Approvals Endpoint · Requires X-API-Key.

Parameters

NameInTypeRequired
client_idquerystring \nullno

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

POST /control/mcp/approvals/{approval_id}/decide#

Decide Approval Endpoint · Requires X-API-Key.

Parameters

NameInTypeRequired
approval_idpathstringyes

Request body · DecideApprovalReq

json
{
  "status": "string"
}
FieldTypeRequiredDescription
statusstringyes
reasonstring \nullno

Responses

  • 200 Successful Response
  • 422 Validation Error · HTTPValidationError

GET /control/mcp/overview#

Get Overview · Requires X-API-Key.

Responses

  • 200 Successful Response