{
  "format": "swarme.contract-manifest.v1",
  "contract_version": "2026-08-21.1",
  "released_at": "2026-08-21",
  "description": "Versioned compatibility surface for public Swarme REST and MCP capability clients.",
  "policy": {
    "deprecation_policy": "/developers#compatibility",
    "changelog": "/contract-changelog.json",
    "manifest": "/contract-manifest.json"
  },
  "rest": {
    "capabilities.search": {"method":"GET","path":"/api/capabilities","auth":["capabilities:read"],"request_required":[],"response_required":["ok","capabilities"]},
    "capabilities.describe": {"method":"GET","path":"/api/capabilities/{slug}","auth":["capabilities:read"],"request_required":["slug"],"response_required":["ok","capability","capability.slug","capability.execution.machine_run_status","capability.input_schema"]},
    "capabilities.quote": {"method":"POST","path":"/api/capabilities/{slug}/quote","auth":["capabilities:quote"],"request_required":["slug"],"response_required":["ok","run_id","quote","quote.quote_id","quote.price"]},
    "capabilities.run": {"method":"POST","path":"/api/capabilities/{slug}/run","auth":["capabilities:run"],"request_required":["slug"],"response_required":["ok","run_id","status"]},
    "capabilities.crt.run": {"method":"POST","path":"/api/capabilities/crt/run","auth":["capabilities:run"],"request_required":["input","input.apex"],"response_required":["ok","run_id","status"],"description":"Success is either a completed CRT result envelope or an idempotent replay envelope; quote_id, client_type, and Idempotency-Key are optional for this free capability."},
    "uploads.create": {"method":"POST","path":"/api/capabilities/{slug}/upload-session","auth":["uploads:write"],"request_required":["slug","filename","mime_type","byte_size"],"response_required":["ok","upload_session","upload_session.upload_id"]},
    "uploads.bytes": {"method":"PUT","path":"/api/capability-uploads/{upload_id}","auth":[],"request_required":["upload_id","Authorization: Bearer upload_token","bytes"],"response_required":["ok","upload_session"]},
    "uploads.bytes_post_compatibility": {"method":"POST","path":"/api/capability-uploads/{upload_id}","auth":[],"request_required":["upload_id","Authorization: Bearer upload_token","bytes"],"response_required":["ok","upload_session"],"description":"Backward-compatible upload-byte method accepted alongside PUT."},
    "uploads.status": {"method":"GET","path":"/api/capability-uploads/{upload_id}","auth":["uploads:write"],"request_required":["upload_id"],"response_required":["ok","upload_session"]},
    "runs.status": {"method":"GET","path":"/api/capability-runs/{run_id}","auth":["capabilities:read"],"request_required":["run_id"],"response_required":["ok","run","run.run_id","run.status"]},
    "runs.cancel": {"method":"POST","path":"/api/capability-runs/{run_id}/cancel","auth":["capabilities:run"],"request_required":["run_id"],"response_required":["ok","run","run.run_id","run.status"]},
    "artifacts.list": {"method":"GET","path":"/api/capability-runs/{run_id}/artifacts","auth":["artifacts:read"],"request_required":["run_id"],"response_required":["ok","run_id","artifacts"]}
  },
  "mcp_tools": {
    "swarme_capabilities_search": {"auth":["capabilities:read"],"input_required":[],"output_required":["capabilities"]},
    "swarme_capability_describe": {"auth":["capabilities:read"],"input_required":["slug"],"output_required":["capability","capability.execution.machine_run_status"]},
    "swarme_account_balance": {"auth":["billing:read"],"input_required":[],"output_required":[]},
    "swarme_tool_quote": {"auth":["capabilities:quote"],"input_required":["slug"],"output_required":["run_id","quote"]},
    "swarme_tool_run": {"auth":["capabilities:run"],"input_required":["slug"],"output_required":["run_id","status"]},
    "swarme_tool_status": {"auth":["capabilities:read"],"input_required":["run_id"],"output_required":["run","run.run_id","run.status"]},
    "swarme_tool_cancel": {"auth":["capabilities:run"],"input_required":["run_id"],"output_required":["run","run.run_id","run.status"]},
    "swarme_tool_artifacts": {"auth":["artifacts:read"],"input_required":["run_id"],"output_required":["run_id","artifacts"]},
    "swarme_upload_session_create": {"auth":["uploads:write"],"input_required":["slug","filename","mime_type","byte_size"],"output_required":["upload_session","upload_session.upload_id"]}
  },
  "enums": {
    "machine_run_status": {"values":["supported","requires_worker","plan_only","describe_only"],"unknown_behavior":"Normalize missing or unknown values to describe_only and block quote/run."},
    "run_status": {"values":["quoted","queued","running","retrying","completed","failed","cancelling","cancelled","planned","requires_client_execution","worker_required","requires_worker","provider_required","payment_required","upload_required","idempotency_reserved"],"unknown_behavior":"Clients must not infer completion or retry safety from an unknown status."}
  },
  "lifecycles": {
    "quote_run": {"states":["describe","quote","run","poll","terminal"],"transitions":["describe->quote","quote->run","run->poll","poll->poll","poll->terminal"],"unknown_behavior":"Stop and re-describe; do not execute an unrecognized transition."},
    "upload": {"states":["reserved","uploading","stored","consumed","expired","failed"],"transitions":["reserved->uploading","uploading->stored","stored->consumed","reserved->expired","stored->expired","uploading->failed"],"unknown_behavior":"Do not reuse, consume, or log an upload with unknown state."},
    "artifact": {"states":["listed","download_authorized","expired"],"transitions":["listed->download_authorized","listed->expired","download_authorized->expired"],"unknown_behavior":"Re-list artifacts and do not assume access for unknown state."}
  },
  "errors": {
    "rest.authentication_required": {"http_status":401,"code":"authentication_required","retryable":false},
    "rest.scope_forbidden": {"http_status":403,"code":"scope_forbidden","retryable":false},
    "rest.payment_or_spend_policy": {"http_status":402,"code":"payment_or_spend_policy","retryable":false},
    "rest.validation": {"http_status":422,"code":"validation_error","retryable":false},
    "rest.not_found": {"http_status":404,"code":"not_found","retryable":false},
    "mcp.tool_error": {"http_status":200,"code":"tool_result_isError","retryable":false},
    "mcp.parse_error": {"http_status":400,"code":"-32700","retryable":false}
  },
  "authentication_scopes": {
    "capabilities:read": {"description":"Search, describe, and read run status."},
    "capabilities:quote": {"description":"Create capability quotes."},
    "capabilities:run": {"description":"Execute and cancel capability runs."},
    "uploads:write": {"description":"Create signed upload sessions."},
    "artifacts:read": {"description":"List permission-checked run artifacts."},
    "billing:read": {"description":"Read account credit and API-client spend state."}
  }
}