Reference

REST API request patterns

The REST API is versioned under the configured base path, normally /v1. Send bearer auth unless the deployment explicitly allows unauthenticated health/version/OpenAPI endpoints.

curl -H "Authorization: Bearer ${MTS_AUTH_TOKEN}" \
  -H "X-Request-Id: docs-example-001" \
  "http://127.0.0.1:8080/v1/version"

Common REST conventions

Convention	Rule
Success envelope	Most JSON successes use `{ "data": ..., "metadata": ... }`. Health and OpenAPI are envelope-exempt.
Error body	Errors use `application/problem+json` with stable `mts_code` values.
Request id	`X-Request-Id` is accepted and returned.
Idempotency	Non-read-only operations require `Idempotency-Key`; statement-dependent operations bind the key to statement identity.
Paging	Page tokens are opaque and bind to principal, request fingerprint, statement/prepared identity, keyspace, dialect, route mode, schema generation, server paging state, and expiry.
OpenAPI	Live contract served at `GET <base>/v1/openapi.json` (unauthenticated by default, envelope-exempt). Load it into any OpenAPI 3.1 viewer for browsable request/response schemas, operation IDs, and `x-mts-*` metadata.

Execute one CQL or MTS SQL statement

curl -X POST "http://127.0.0.1:8080/v1/executions" \
  -H "Authorization: Bearer ${MTS_AUTH_TOKEN}" \
  -H "Idempotency-Key: exec-tenant-alpha-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "dialect": "cql",
    "keyspace": "app",
    "statement": "SELECT id, title FROM docs WHERE tenant = ? AND id = ?",
    "binds": [
      { "type": "text", "value": "tenant-alpha" },
      { "type": "text", "value": "d1" }
    ],
    "page_size": 100
  }'

curl -X POST "http://127.0.0.1:8080/v1/executions" \
  -H "Authorization: Bearer ${MTS_AUTH_TOKEN}" \
  -H "Idempotency-Key: exec-sql-tenant-alpha-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "dialect": "sql",
    "schema": "app",
    "statement": "SELECT id, title FROM docs WHERE tenant = $1 AND id = $2",
    "binds": [
      { "type": "text", "value": "tenant-alpha" },
      { "type": "text", "value": "d1" }
    ]
  }'

Show 200 response (CQL execution)

{
  "api_version": "v1",
  "data": {
    "execution_id": "exe_01HZXCQL0001",
    "result_set": {
      "applied": null,
      "columns": [
        {
          "name": "user_id",
          "type": "uuid"
        },
        {
          "name": "display_name",
          "type": "text"
        }
      ],
      "next_page_token": null,
      "row_count": 1,
      "rows": [
        [
          {
            "type": "uuid",
            "value": "0f9a2b4c-7d68-4f01-9c3a-2a4b8c16d901"
          },
          {
            "type": "text",
            "value": "Ada"
          }
        ]
      ]
    },
    "stats": {
      "db_duration": "8ms",
      "duration": "12ms",
      "rows_returned": 1
    }
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "8ms",
      "idempotency": "idempotent",
      "request_id": "req_01HZXCQL0001",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "select",
      "trace_id": "trc_01HZXCQL0001"
    },
    "page": {
      "has_more": false,
      "size": 1
    },
    "route_evidence": null,
    "route_mode": "any",
    "server_time": "2026-06-05T12:00:00Z",
    "warnings": []
  },
  "request_id": "req_01HZXCQL0001",
  "trace_id": "trc_01HZXCQL0001"
}

Show 200 response (MTS SQL execution)

{
  "api_version": "v1",
  "data": {
    "execution_id": "exe_01HZXSQL0001",
    "result_set": {
      "applied": null,
      "columns": [],
      "next_page_token": null,
      "row_count": 0,
      "rows": []
    },
    "stats": {
      "db_duration": "6ms",
      "duration": "9ms",
      "rows_returned": 0
    }
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-2",
      "duration": "6ms",
      "idempotency": "idempotent",
      "request_id": "req_01HZXSQL0001",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "insert",
      "trace_id": "trc_01HZXSQL0001"
    },
    "page": {
      "has_more": false,
      "size": 0
    },
    "route_evidence": null,
    "route_mode": "any",
    "server_time": "2026-06-05T12:00:01Z",
    "warnings": []
  },
  "request_id": "req_01HZXSQL0001",
  "trace_id": "trc_01HZXSQL0001"
}

Show 409 error (idempotency conflict)

{
  "detail": "Idempotency-Key order-2041 was first recorded with a different request fingerprint; the retained outcome belongs to the original request",
  "hint": "replay the original request unchanged to receive its retained outcome, or send a new Idempotency-Key for a different mutation",
  "idempotency": "unknown",
  "mts_code": "idempotency_conflict",
  "request_id": "req_01HZXIDM0002",
  "retryable": false,
  "status": 409,
  "surface": "mts-rest-api/v1",
  "title": "idempotency key conflict",
  "type": "urn:mts:problem:idempotency_conflict"
}

Prepared statements over REST

curl -X POST "http://127.0.0.1:8080/v1/prepared-statements" \
  -H "Authorization: Bearer ${MTS_AUTH_TOKEN}" \
  -H "Idempotency-Key: prep-doc-by-id-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "dialect": "sql",
    "keyspace": "app",
    "statement": "SELECT id, title FROM docs WHERE tenant = $1 AND id = $2"
  }'

curl -X POST "http://127.0.0.1:8080/v1/prepared-statements/{prepared_id}/executions" \
  -H "Authorization: Bearer ${MTS_AUTH_TOKEN}" \
  -H "Idempotency-Key: prep-doc-by-id-v1-exec-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "binds": [
      { "type": "text", "value": "tenant-alpha" },
      { "type": "text", "value": "d1" }
    ]
  }'

Show 200 response (prepared execution)

{
  "api_version": "v1",
  "data": {
    "execution_id": "exe_01HZXPRE0001",
    "result_set": {
      "applied": null,
      "columns": [
        {
          "name": "user_id",
          "type": "uuid"
        },
        {
          "name": "display_name",
          "type": "text"
        }
      ],
      "next_page_token": null,
      "row_count": 1,
      "rows": [
        [
          {
            "type": "uuid",
            "value": "0f9a2b4c-7d68-4f01-9c3a-2a4b8c16d901"
          },
          {
            "type": "text",
            "value": "Ada"
          }
        ]
      ]
    },
    "stats": {
      "db_duration": "4ms",
      "duration": "7ms",
      "rows_returned": 1
    }
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-2",
      "duration": "4ms",
      "idempotency": "idempotent",
      "request_id": "req_01HZXPRE0001",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "select",
      "trace_id": "trc_01HZXPRE0001"
    },
    "page": {
      "has_more": false,
      "size": 1
    },
    "route_evidence": {
      "coordinator_node": "node-2",
      "endpoint_trust": "verified",
      "execution_location": "owner-direct",
      "fallback_decision": null,
      "fallback_reason": null,
      "fence_state": "valid",
      "lease_state": "held",
      "owner_endpoint": "10.0.0.12:9042",
      "owner_epoch": 17,
      "owner_node": "node-2",
      "route_eligible": true,
      "route_mode": "prefer-owner",
      "route_token_status": "valid",
      "stale_owner_status": "fresh",
      "table": "app.users",
      "tablet_id": "tbl_0042",
      "target_classification": "single-tablet"
    },
    "route_mode": "prefer-owner",
    "server_time": "2026-06-05T12:00:02Z",
    "warnings": []
  },
  "request_id": "req_01HZXPRE0001",
  "trace_id": "trc_01HZXPRE0001"
}

Show 422 error (owner route ineligible)

{
  "detail": "route certification classified the statement as fanout across 3 tablets; require-owner refuses multi-tablet execution and never falls back to a coordinator",
  "hint": "use route_mode any or prefer-owner for fanout statements",
  "mts_code": "owner_route_ineligible",
  "request_id": "req_01HZXRTE0001",
  "retryable": false,
  "route_evidence": {
    "coordinator_node": "node-1",
    "execution_location": "not-executed",
    "route_eligible": false,
    "route_mode": "require-owner",
    "target_classification": "fanout"
  },
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "require-owner routing ineligible",
  "type": "urn:mts:problem:owner_route_ineligible"
}

REST data helper shapes

curl -X POST "http://127.0.0.1:8080/v1/data/app/docs/rows/lookup" \
  -H "Authorization: Bearer ${MTS_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "key": {
      "tenant": { "type": "text", "value": "tenant-alpha" },
      "id": { "type": "text", "value": "d1" }
    },
    "projection": ["tenant", "id", "title", "body"]
  }'

curl -X POST "http://127.0.0.1:8080/v1/explain" \
  -H "Authorization: Bearer ${MTS_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "dialect": "sql",
    "statement": "SELECT id FROM app.docs WHERE tenant = $1 AND body MATCH $2 LIMIT 10",
    "binds": [
      { "type": "text", "value": "tenant-alpha" },
      { "type": "text", "value": "refund" }
    ],
    "format": "json",
    "admission": true
  }'

Show 200 response (row lookup)

{
  "api_version": "v1",
  "data": {
    "result_set": {
      "applied": null,
      "columns": [
        {
          "name": "tenant_id",
          "type": "text"
        },
        {
          "name": "user_id",
          "type": "uuid"
        },
        {
          "name": "display_name",
          "type": "text"
        }
      ],
      "next_page_token": null,
      "row_count": 1,
      "rows": [
        [
          {
            "type": "text",
            "value": "tenant-a"
          },
          {
            "type": "uuid",
            "value": "0f9a2b4c-7d68-4f01-9c3a-2a4b8c16d901"
          },
          {
            "type": "text",
            "value": "Ada"
          }
        ]
      ]
    }
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "3ms",
      "idempotency": "idempotent",
      "request_id": "req_01HZXLKP0001",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "select",
      "trace_id": "trc_01HZXLKP0001"
    },
    "page": {
      "has_more": false,
      "size": 1
    },
    "route_evidence": null,
    "route_mode": "any",
    "server_time": "2026-06-05T12:00:03Z",
    "warnings": []
  },
  "request_id": "req_01HZXLKP0001",
  "trace_id": "trc_01HZXLKP0001"
}

Show 422 error (unsafe scan refused)

{
  "detail": "predicate on column status is not bounded by any queryable access path; admission refused the unbounded scan before execution",
  "execution_evidence": {
    "admission_decision": "refused",
    "idempotency": "idempotent",
    "request_id": "req_01HZXSCN0001",
    "retryable": false,
    "safe_retry": "safe",
    "statement_family": "select"
  },
  "hint": "create a queryable access path on (status) or bound the query by primary key",
  "mts_code": "unsafe_scan_refused",
  "request_id": "req_01HZXSCN0001",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "unsafe row query refused",
  "type": "urn:mts:problem:unsafe_scan_refused"
}

REST operation inventory

Safety (1)

POST /v1/actions/preview Preview safety class, affected scope, idempotency, and confirmation needs. previewAction execute read-only 200, 400, 401, 403, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "dry_run": true,
  "operation": {
    "arguments": {},
    "binds": [
      {
        "encoding": "base64",
        "is_null": true,
        "type": "text"
      }
    ],
    "dialect": "cql",
    "execution_id": "exe_<RID>",
    "format": "csv",
    "inline_rows": [
      {}
    ],
    "job_id": "00000000-0000-0000-0000-000000000001",
    "keys": [
      {}
    ],
    "keyspace": "app",
    "kind": "statement",
    "manifest": {},
    "operation": "string",
    "operations": [
      {
        "binds": [],
        "key": {},
        "keyspace": "app",
        "kind": "statement",
        "statement": "SELECT 1",
        "table": "users",
        "values": {}
      }
    ],
    "options": {},
    "prepared_id": "prep_<RID>",
    "route_mode": "any",
    "row": {},
    "set": {},
    "statement": "SELECT 1",
    "statements": [
      {
        "binds": [],
        "statement": "SELECT 1"
      }
    ],
    "table": "users"
  },
  "profile": "string",
  "request_id": "req_<RID>",
  "timeout": "string",
  "trace": true
}

200 response body

{
  "api_version": "v1",
  "data": {
    "affected_scope": {},
    "confirmation_required": true,
    "confirmation_token": "string",
    "expires_at": "2026-06-17T12:00:00Z",
    "idempotency": "idempotent",
    "operation_fingerprint": "string",
    "safety_class": "read-only"
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

ExplainAdvice (2)

POST /v1/advice Request query/modeling/access-path advice. adviseStatement execute read-only 200, 400, 401, 403, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "dialect": "cql",
  "keyspace": "app",
  "profile": "string",
  "request_id": "req_<RID>",
  "statement": "SELECT 1",
  "timeout": "string",
  "trace": true
}

200 response body

{
  "api_version": "v1",
  "data": {
    "advice": [
      {
        "detail": "...",
        "kind": "export"
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

POST /v1/explain Explain a statement through public admission surfaces. explainStatement execute read-only 200, 400, 401, 403, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "binds": [
    {
      "encoding": "base64",
      "is_null": true,
      "type": "text"
    }
  ],
  "dialect": "cql",
  "keyspace": "app",
  "profile": "string",
  "request_id": "req_<RID>",
  "route_mode": "any",
  "statement": "SELECT 1",
  "timeout": "string",
  "trace": true
}

200 response body

{
  "api_version": "v1",
  "data": {
    "admitted": true,
    "bounded_serving_evidence": {
      "evidence_version": "string"
    },
    "decision": {},
    "proof_sources": [
      "string"
    ],
    "queryability": "string",
    "suggested_access_paths": [
      "string"
    ],
    "target_classification": "single-tablet"
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

Batches (1)

POST /v1/batches Execute a finite batch of statements/helper operations. createBatch execute statement-dependent 200, 400, 401, 403, 409, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "confirmation_token": "string",
  "dialect": "cql",
  "keyspace": "app",
  "operations": [
    {
      "binds": [
        {
          "encoding": "base64",
          "is_null": true,
          "type": "text"
        }
      ],
      "key": {},
      "keyspace": "app",
      "kind": "statement",
      "statement": "SELECT 1",
      "table": "users",
      "values": {}
    }
  ],
  "profile": "string",
  "request_id": "req_<RID>",
  "route_mode": "any",
  "timeout": "string",
  "trace": true
}

200 response body

{
  "api_version": "v1",
  "data": {
    "final_state": "completed",
    "results": [
      {
        "index": 0,
        "status": "succeeded"
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

Capabilities (3)

GET /v1/capabilities REST and downstream MTS DB capability summaries. getCapabilities capabilities read-only 200, 400, 401, 403, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "db_capabilities": [
      {
        "name": "users",
        "state": "active",
        "version": "string"
      }
    ],
    "rest_capabilities": [
      {
        "name": "users",
        "state": "active",
        "version": "string"
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/openapi.json OpenAPI 3.1 document for the exact running API shape. getOpenApiDocument version read-only 200, 400, 401, 403, 429, 500

No request body.

Response body schema documented in /v1/openapi.json.

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/version API/server/build/schema version metadata. getVersion version read-only 200, 400, 401, 403, 429, 500

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "api_version": "v1",
    "build": {
      "built_at": "string",
      "commit": "string"
    },
    "openapi_schema_version": "string",
    "server": "mts-api-server",
    "server_version": "string",
    "supported_db_surfaces": [
      {
        "name": "users",
        "version": "string"
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

Catalog (8)

GET /v1/catalog/access-paths List access paths and queryability. listAccessPaths schema-read read-only 200, 400, 401, 403, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "keyspace": "app",
        "kind": "export",
        "name": "users",
        "queryable": true,
        "state": "active",
        "table": "users"
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/catalog/functions List functions/routines. listFunctions schema-read read-only 200, 400, 401, 403, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "keyspace": "app",
        "kind": "export",
        "name": "users",
        "signature": "string"
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/catalog/keyspaces List visible keyspaces/databases. listKeyspaces schema-read read-only 200, 400, 401, 403, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "name": "users",
        "options": {}
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/catalog/keyspaces/{keyspace} Inspect a keyspace. getKeyspace schema-read read-only 200, 400, 401, 403, 404, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "name": "users",
    "options": {}
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/catalog/keyspaces/{keyspace}/tables List visible tables. listTables schema-read read-only 200, 400, 401, 403, 404, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "keyspace": "app",
        "kind": "export",
        "name": "users",
        "options": {}
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/catalog/keyspaces/{keyspace}/tables/{table} Inspect a table. getTable schema-read read-only 200, 400, 401, 403, 404, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "keyspace": "app",
    "kind": "export",
    "name": "users",
    "options": {}
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/catalog/keyspaces/{keyspace}/tables/{table}/columns List columns. listColumns schema-read read-only 200, 400, 401, 403, 404, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "keyspace": "app",
        "kind": "partition-key",
        "name": "users",
        "position": 0,
        "table": "users",
        "type": "text"
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/catalog/roles List visible roles/users. listRoles schema-read read-only 200, 400, 401, 403, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "name": "users",
        "options": {}
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

Cluster (11)

GET /v1/cluster/access-paths Cluster access-path state. getClusterAccessPaths cluster-read read-only 200, 400, 401, 403, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "keyspace": "app",
        "kind": "export",
        "name": "users",
        "queryable": true,
        "state": "active",
        "table": "users"
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/cluster/builds Builds. getClusterBuilds cluster-read read-only 200, 400, 401, 403, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "access_path": "string",
        "build_id": "00000000-0000-0000-0000-000000000001",
        "progress": {},
        "state": "active"
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/cluster/features Feature states. getClusterFeatures cluster-read read-only 200, 400, 401, 403, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "name": "users",
        "state": "active"
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/cluster/jobs Background jobs. getClusterJobs cluster-read read-only 200, 400, 401, 403, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "job_id": "00000000-0000-0000-0000-000000000001",
        "kind": "export",
        "progress": {},
        "started_at": "2026-06-17T12:00:00Z",
        "state": "active"
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/cluster/leases Lease/fence view. getClusterLeases cluster-read read-only 200, 400, 401, 403, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "epoch": 0,
        "expires_at": "2026-06-17T12:00:00Z",
        "fence_state": "valid",
        "holder_node": "node-1",
        "resource": "string",
        "revision": 0
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/cluster/metrics Bounded metric snapshots. getClusterMetrics cluster-read read-only 200, 400, 401, 403, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "labels": {},
        "name": "users",
        "value": 0
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/cluster/nodes Nodes/liveness. getClusterNodes cluster-read read-only 200, 400, 401, 403, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "endpoint": "10.0.0.12:9042",
        "liveness": "string",
        "node_id": "00000000-0000-0000-0000-000000000001",
        "state": "active",
        "version": "string"
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/cluster/residence Residence/tiering state. getClusterResidence cluster-read read-only 200, 400, 401, 403, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "scope": "string",
        "state": "active",
        "tier": "string"
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/cluster/routing Routing/owner view. getClusterRouting cluster-read read-only 200, 400, 401, 403, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "lease_state": "held",
        "owner_epoch": 0,
        "owner_node": "node-1",
        "tablet_id": "00000000-0000-0000-0000-000000000001"
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/cluster/summary Cluster summary. getClusterSummary cluster-read read-only 200, 400, 401, 403, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "cluster_name": "string",
    "features_summary": {},
    "nodes_live": 0,
    "nodes_total": 0,
    "version_summary": {}
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/cluster/tablets Tablet placement/state. getClusterTablets cluster-read read-only 200, 400, 401, 403, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "epoch": 0,
        "keyspace": "app",
        "owner_node": "node-1",
        "range": "string",
        "state": "active",
        "table": "users",
        "tablet_id": "00000000-0000-0000-0000-000000000001"
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

Data (5)

PATCH /v1/data/{keyspace}/{table}/rows Update selected columns by complete primary key. patchRows execute surface-resolved 200, 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "confirmation_token": "string",
  "if_exists": true,
  "keys": [
    {}
  ],
  "profile": "string",
  "request_id": "req_<RID>",
  "route_mode": "any",
  "set": {},
  "timeout": "string",
  "trace": true,
  "ttl": "string"
}

200 response body

{
  "api_version": "v1",
  "data": {
    "applied": true
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

POST /v1/data/{keyspace}/{table}/rows Insert/upsert row data. upsertRow execute surface-resolved 200, 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "confirmation_token": "string",
  "if_not_exists": true,
  "profile": "string",
  "request_id": "req_<RID>",
  "route_mode": "any",
  "row": {},
  "timeout": "string",
  "trace": true,
  "ttl": "string"
}

200 response body

{
  "api_version": "v1",
  "data": {
    "applied": true
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

POST /v1/data/{keyspace}/{table}/rows/delete Delete rows by complete primary key. deleteRows execute surface-resolved 200, 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "confirmation_token": "string",
  "if_exists": true,
  "keys": [
    {}
  ],
  "profile": "string",
  "request_id": "req_<RID>",
  "route_mode": "any",
  "timeout": "string",
  "trace": true
}

200 response body

{
  "api_version": "v1",
  "data": {
    "applied": true
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

POST /v1/data/{keyspace}/{table}/rows/lookup Lookup rows by complete primary key. lookupRows execute read-only 200, 400, 401, 403, 404, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "columns": [
    "string"
  ],
  "keys": [
    {}
  ],
  "profile": "string",
  "request_id": "req_<RID>",
  "route_mode": "any",
  "timeout": "string",
  "trace": true
}

200 response body

{
  "api_version": "v1",
  "data": {
    "result_set": {
      "columns": [
        {}
      ],
      "next_page_token": "string",
      "row_count": 0,
      "rows": [
        []
      ]
    }
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "page": {
      "has_more": true,
      "size": 0
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

POST /v1/data/{keyspace}/{table}/rows/query Run a bounded structured row query. queryRows execute read-only 200, 400, 401, 403, 404, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "columns": [
    "string"
  ],
  "limit": 0,
  "order_by": [
    {
      "column": "string",
      "direction": "asc"
    }
  ],
  "page_size": 0,
  "predicates": [
    {
      "column": "string",
      "op": "eq",
      "value": {
        "encoding": "base64",
        "is_null": true,
        "type": "text"
      }
    }
  ],
  "profile": "string",
  "request_id": "req_<RID>",
  "route_mode": "any",
  "timeout": "string",
  "trace": true
}

200 response body

{
  "api_version": "v1",
  "data": {
    "execution_id": "exe_<RID>",
    "result_set": {
      "columns": [
        {}
      ],
      "next_page_token": "string",
      "row_count": 0,
      "rows": [
        []
      ]
    }
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "page": {
      "has_more": true,
      "size": 0
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

Execution (4)

POST /v1/executions Execute exactly one CQL or MTS SQL statement. createExecution execute statement-dependent 200, 400, 401, 403, 409, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "binds": [
    {
      "encoding": "base64",
      "is_null": true,
      "type": "text"
    }
  ],
  "confirmation_token": "string",
  "consistency": "string",
  "dialect": "cql",
  "keyspace": "app",
  "page_size": 0,
  "profile": "string",
  "request_id": "req_<RID>",
  "route_mode": "any",
  "statement": "SELECT 1",
  "timeout": "string",
  "trace": true
}

200 response body

{
  "api_version": "v1",
  "data": {
    "execution_id": "exe_<RID>",
    "result_set": {
      "columns": [
        {}
      ],
      "next_page_token": "string",
      "row_count": 0,
      "rows": [
        []
      ]
    },
    "stats": {
      "duration": "string",
      "rows_returned": 0
    }
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "page": {
      "has_more": true,
      "size": 0
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

DELETE /v1/executions/{execution_id} Cancel an in-flight execution. cancelExecution execute idempotent-write 204, 400, 401, 403, 404, 409, 410, 422, 429, 500, 502, 503, 504

No request body.

No response body.

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/executions/{execution_id} Retrieve retained execution metadata. getExecution execute read-only 200, 400, 401, 403, 404, 410, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "created_at": "2026-06-17T12:00:00Z",
    "dialect": "cql",
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "execution_id": "exe_<RID>",
    "expires_at": "2026-06-17T12:00:00Z",
    "request_id": "req_<RID>",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "state": "running",
    "statement_digest": "string"
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

POST /v1/executions/{execution_id}/pages Fetch a subsequent result page. fetchExecutionPage execute read-only 200, 400, 401, 403, 404, 409, 410, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "page_size": 0,
  "page_token": "string",
  "profile": "string",
  "request_id": "req_<RID>",
  "timeout": "string",
  "trace": true
}

200 response body

{
  "api_version": "v1",
  "data": {
    "execution_id": "exe_<RID>",
    "result_set": {
      "columns": [
        {}
      ],
      "next_page_token": "string",
      "row_count": 0,
      "rows": [
        []
      ]
    },
    "stats": {
      "duration": "string",
      "rows_returned": 0
    }
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "page": {
      "has_more": true,
      "size": 0
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

Exports (4)

POST /v1/exports Submit an export/copy-out job. createExport export surface-resolved 202, 400, 401, 403, 409, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "confirmation_token": "string",
  "dry_run": true,
  "format": "csv",
  "keyspace": "app",
  "manifest": {},
  "options": {
    "compression": "string",
    "max_part_bytes": 0
  },
  "profile": "string",
  "request_id": "req_<RID>",
  "table": "users",
  "timeout": "string",
  "trace": true
}

202 response body

{
  "api_version": "v1",
  "data": {
    "cancellable": true,
    "created_at": "2026-06-17T12:00:00Z",
    "format": "csv",
    "job_id": "00000000-0000-0000-0000-000000000001",
    "kind": "export",
    "manifest": {},
    "parts": [
      {
        "available": true,
        "part_id": "00000000-0000-0000-0000-000000000001",
        "size": 0
      }
    ],
    "progress": {
      "bytes_processed": 0,
      "rejects": 0,
      "rows_processed": 0
    },
    "state": "pending"
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/exports/{job_id} Inspect export status. getExport export read-only 200, 400, 401, 403, 404, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "cancellable": true,
    "created_at": "2026-06-17T12:00:00Z",
    "format": "csv",
    "job_id": "00000000-0000-0000-0000-000000000001",
    "kind": "export",
    "manifest": {},
    "parts": [
      {
        "available": true,
        "part_id": "00000000-0000-0000-0000-000000000001",
        "size": 0
      }
    ],
    "progress": {
      "bytes_processed": 0,
      "rejects": 0,
      "rows_processed": 0
    },
    "state": "pending"
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

POST /v1/exports/{job_id}/cancel Cancel an export if possible. cancelExport export idempotent-write 204, 400, 401, 403, 404, 409, 422, 429, 500, 502, 503, 504

No request body.

No response body.

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/exports/{job_id}/parts/{part_id} Download an export part. downloadExportPart export read-only 200, 400, 401, 403, 404, 410, 429, 500, 502, 503, 504

No request body.

No response body.

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

Health (2)

GET /v1/health/live Process liveness. getLiveness health read-only 200, 400, 401, 403, 429, 500

No request body.

200 response body

{
  "live": true,
  "replica_id": "00000000-0000-0000-0000-000000000001"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/health/ready Replica readiness with cluster connectivity and required surface versions. getReadiness health read-only 200, 400, 401, 403, 429, 500, 503

No request body.

200 response body

{
  "capability_versions": [
    {
      "name": "users",
      "version": "string"
    }
  ],
  "checks": [
    {
      "detail": "...",
      "name": "users",
      "state": "ok"
    }
  ],
  "ready": true,
  "replica_id": "00000000-0000-0000-0000-000000000001"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

Imports (3)

POST /v1/imports Submit an import/copy-in job. createImport import surface-resolved 202, 400, 401, 403, 409, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "confirmation_token": "string",
  "dry_run": true,
  "format": "csv",
  "inline_rows": [
    {}
  ],
  "keyspace": "app",
  "manifest": {},
  "options": {
    "delimiter": "string",
    "error_sample_size": 0,
    "header": true,
    "max_rejects": 0,
    "resume_token": "string"
  },
  "profile": "string",
  "request_id": "req_<RID>",
  "table": "users",
  "timeout": "string",
  "trace": true
}

202 response body

{
  "api_version": "v1",
  "data": {
    "cancellable": true,
    "created_at": "2026-06-17T12:00:00Z",
    "format": "csv",
    "job_id": "00000000-0000-0000-0000-000000000001",
    "kind": "import",
    "manifest": {},
    "progress": {
      "bytes_processed": 0,
      "rejects": 0,
      "rows_processed": 0
    },
    "state": "pending"
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/imports/{job_id} Inspect import status. getImport import read-only 200, 400, 401, 403, 404, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "cancellable": true,
    "created_at": "2026-06-17T12:00:00Z",
    "format": "csv",
    "job_id": "00000000-0000-0000-0000-000000000001",
    "kind": "import",
    "manifest": {},
    "progress": {
      "bytes_processed": 0,
      "rejects": 0,
      "rows_processed": 0
    },
    "state": "pending"
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

POST /v1/imports/{job_id}/cancel Cancel an import if possible. cancelImport import idempotent-write 204, 400, 401, 403, 404, 409, 422, 429, 500, 502, 503, 504

No request body.

No response body.

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

PreparedStatements (5)

GET /v1/prepared-statements List retained prepared handles. listPreparedStatements execute read-only 200, 400, 401, 403, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "dialect": "cql",
        "metadata_generation": "string",
        "parameters": [
          {}
        ],
        "prepared_id": "prep_<RID>",
        "result_columns": [],
        "retention": "string",
        "route_mode": "any"
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

POST /v1/prepared-statements Prepare a statement. createPreparedStatement execute idempotent-write 201, 400, 401, 403, 409, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "dialect": "cql",
  "keyspace": "app",
  "profile": "string",
  "request_id": "req_<RID>",
  "route_mode": "any",
  "statement": "SELECT 1",
  "timeout": "string",
  "trace": true
}

201 response body

{
  "api_version": "v1",
  "data": {
    "dialect": "cql",
    "metadata_generation": "string",
    "parameters": [
      {
        "name": "users",
        "type": "text"
      }
    ],
    "prepared_id": "prep_<RID>",
    "result_columns": [
      {
        "name": "users",
        "type": "text"
      }
    ],
    "retention": "string",
    "route_mode": "any"
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

DELETE /v1/prepared-statements/{prepared_id} Release a prepared handle. deletePreparedStatement execute idempotent-write 204, 400, 401, 403, 404, 409, 410, 422, 429, 500, 502, 503, 504

No request body.

No response body.

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/prepared-statements/{prepared_id} Inspect prepared metadata. getPreparedStatement execute read-only 200, 400, 401, 403, 404, 410, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "dialect": "cql",
    "metadata_generation": "string",
    "parameters": [
      {
        "name": "users",
        "type": "text"
      }
    ],
    "prepared_id": "prep_<RID>",
    "result_columns": [
      {
        "name": "users",
        "type": "text"
      }
    ],
    "retention": "string",
    "route_mode": "any"
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

POST /v1/prepared-statements/{prepared_id}/executions Execute a prepared statement with typed binds. executePreparedStatement execute statement-dependent 200, 400, 401, 403, 404, 409, 410, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "binds": [
    {
      "encoding": "base64",
      "is_null": true,
      "type": "text"
    }
  ],
  "confirmation_token": "string",
  "consistency": "string",
  "page_size": 0,
  "profile": "string",
  "request_id": "req_<RID>",
  "route_mode": "any",
  "timeout": "string",
  "trace": true
}

200 response body

{
  "api_version": "v1",
  "data": {
    "execution_id": "exe_<RID>",
    "result_set": {
      "columns": [
        {}
      ],
      "next_page_token": "string",
      "row_count": 0,
      "rows": [
        []
      ]
    },
    "stats": {
      "duration": "string",
      "rows_returned": 0
    }
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "page": {
      "has_more": true,
      "size": 0
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

Routing (1)

POST /v1/routes/certifications Request bounded server-certified route evidence. certifyRoute route-certify read-only 200, 400, 401, 403, 404, 409, 410, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "binds": [
    {
      "encoding": "base64",
      "is_null": true,
      "type": "text"
    }
  ],
  "columns": [
    "string"
  ],
  "dialect": "cql",
  "format": "csv",
  "helper_kind": "row-lookup",
  "if_exists": true,
  "if_not_exists": true,
  "keys": [
    {}
  ],
  "keyspace": "app",
  "kind": "statement",
  "limit": 0,
  "manifest": {},
  "operations": [
    {
      "binds": [
        {
          "encoding": "base64",
          "is_null": true,
          "type": "text"
        }
      ],
      "key": {},
      "keyspace": "app",
      "kind": "statement",
      "statement": "SELECT 1",
      "table": "users",
      "values": {}
    }
  ],
  "options": {},
  "order_by": [
    {
      "column": "string",
      "direction": "asc"
    }
  ],
  "page_size": 0,
  "page_token": "string",
  "predicates": [
    {
      "column": "string",
      "op": "eq",
      "value": {
        "encoding": "base64",
        "is_null": true,
        "type": "text"
      }
    }
  ],
  "prepared_id": "prep_<RID>",
  "profile": "string",
  "request_id": "req_<RID>",
  "route_mode": "any",
  "row": {},
  "set": {},
  "statement": "SELECT 1",
  "table": "users",
  "timeout": "string",
  "trace": true,
  "ttl": "string"
}

200 response body

{
  "api_version": "v1",
  "data": {
    "coordinator_node": "node-1",
    "endpoint_trust": "verified",
    "route_eligible": true,
    "route_mode": "any",
    "target_classification": "single-tablet"
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

Schema (1)

POST /v1/schema/ddl Render canonical DDL for a scope. renderDdl schema-read read-only 200, 400, 401, 403, 404, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "access_path": "string",
  "dialect": "cql",
  "keyspace": "app",
  "profile": "string",
  "request_id": "req_<RID>",
  "role": "string",
  "scope": "keyspace",
  "table": "users",
  "timeout": "string",
  "trace": true
}

200 response body

{
  "api_version": "v1",
  "data": {
    "ddl": "string",
    "scope": "keyspace"
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

Transactions (1)

POST /v1/scripts/transactions Execute a finite script-compatible transaction. createScriptTransaction execute statement-dependent 200, 400, 401, 403, 409, 413, 415, 422, 429, 500, 502, 503, 504

Request body

{
  "confirmation_token": "string",
  "dialect": "cql",
  "keyspace": "app",
  "profile": "string",
  "request_id": "req_<RID>",
  "route_mode": "any",
  "statements": [
    {
      "binds": [
        {
          "encoding": "base64",
          "is_null": true,
          "type": "text"
        }
      ],
      "statement": "SELECT 1"
    }
  ],
  "timeout": "string",
  "trace": true
}

200 response body

{
  "api_version": "v1",
  "data": {
    "final_state": "committed",
    "results": [
      {
        "index": 0,
        "status": "succeeded"
      }
    ],
    "rollback_status": "none"
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

Tracing (2)

GET /v1/traces Search traces by authorized filters. listTraces trace-read read-only 200, 400, 401, 403, 410, 422, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "items": [
      {
        "coordinator": "string",
        "duration": "string",
        "events": [
          {}
        ],
        "request_id": "req_<RID>",
        "started_at": "2026-06-17T12:00:00Z",
        "trace_id": "req_<RID>"
      }
    ]
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "has_more": true,
    "limit": 0,
    "next_page_token": "string",
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}

GET /v1/traces/{trace_id} Fetch one trace. getTrace trace-read read-only 200, 400, 401, 403, 404, 429, 500, 502, 503, 504

No request body.

200 response body

{
  "api_version": "v1",
  "data": {
    "coordinator": "string",
    "duration": "string",
    "events": [
      {
        "activity": "string",
        "at": "2026-06-17T12:00:00Z",
        "node": "node-1"
      }
    ],
    "request_id": "req_<RID>",
    "started_at": "2026-06-17T12:00:00Z",
    "trace_id": "req_<RID>"
  },
  "metadata": {
    "execution_evidence": {
      "admission_decision": "admitted",
      "coordinator_node": "node-1",
      "duration": "string",
      "idempotency": "idempotent",
      "request_id": "req_<RID>",
      "retryable": true,
      "safe_retry": "safe",
      "statement_family": "string"
    },
    "route_evidence": {
      "coordinator_node": "node-1",
      "endpoint_trust": "verified",
      "route_eligible": true,
      "route_mode": "any",
      "target_classification": "single-tablet"
    },
    "route_mode": "any",
    "server_time": "2026-06-17T12:00:00Z",
    "warnings": [
      "string"
    ]
  },
  "request_id": "req_<RID>"
}

422 error (admission refused, example)

{
  "detail": "the planner refused the request before execution",
  "hint": "...",
  "idempotency": "unknown",
  "mts_code": "admission_refused",
  "request_id": "req_<RID>",
  "retryable": false,
  "status": 422,
  "surface": "mts-rest-api/v1",
  "title": "admission refused",
  "type": "urn:mts:problem:admission_refused"
}