{ "openapi": "3.1.0", "info": { "title": "Hekate Gate API", "version": "0.1.0", "description": "Security preflight API for AI agents before they call, trust or pay an API, MCP tool or on-chain workflow. Agent proposes; Policy decides; Signer signs; Verifier validates; Ledger records.", "contact": { "name": "Hekate Gate", "url": "https://hekategate.com", "email": "support@hekategate.com" }, "license": { "name": "Proprietary" } }, "externalDocs": { "description": "Copy-paste Hekate Lite examples and public JSON fixtures", "url": "https://hekategate.com/examples" }, "servers": [ { "url": "https://hekategate.com", "description": "Public Hekate Lite private beta" }, { "url": "http://127.0.0.1:3030", "description": "Local dev" }, { "url": "https://api.hekategate.com", "description": "Production" } ], "tags": [ { "name": "missions", "description": "Mission lifecycle: create, quote, execute, audit." }, { "name": "templates", "description": "Reusable mission templates with var substitution." }, { "name": "providers", "description": "x402 provider registry, scorecard, certification." }, { "name": "certification", "description": "Provider certification application + review." }, { "name": "billing", "description": "Orchestration fee accounting + Stripe export." }, { "name": "webhooks", "description": "Event subscriptions + delivery debugger." }, { "name": "admin", "description": "Wallet kill switch and operator controls." }, { "name": "hekate-lite", "description": "Public private-beta Hekate preflight endpoints for MCP, x402, permissions, tool chains, receipts, and Ergo/Sage flows." }, { "name": "exports", "description": "CSV exports for finance + audit." }, { "name": "stats", "description": "Aggregated stats for dashboards." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Static token from MC_API_TOKENS (org_id:token or org_id:token:scope1|scope2), DB-backed mc_key token issued by /v1/admin/api-keys, or RS256/ES256 JWT verified against MC_OIDC_ISSUER with scopes from scope/scp/permissions/roles. Scoped deployments should grant explicit route scopes such as missions:read, agentsec:scan, provider:read, provider:write, webhooks:read, billing:read, exports:read, or admin:* only where needed." } }, "schemas": { "HekateFinding": { "type": "object", "properties": { "type": { "type": "string" }, "severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] }, "title": { "type": "string" }, "reason": { "type": "string" }, "evidence": { "type": "object" }, "recommendation": { "type": "string" } } }, "HekateReceipt": { "type": "object", "properties": { "receipt_type": { "type": "string", "const": "agentsec.security_preflight.v1" }, "brand": { "type": "string", "const": "Hekate Gate" }, "receipt_id": { "type": "string" }, "subject": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "config_hash": { "type": "string" } } }, "policy_hash": { "type": "string" }, "scanner_version": { "type": "string" }, "decision": { "type": "string", "enum": ["allow", "warn", "block"] }, "risk_score": { "type": "number" }, "critical_findings": { "type": "integer" }, "high_findings": { "type": "integer" }, "evidence_hash": { "type": "string" }, "issued_at": { "type": "string", "format": "date-time" }, "issuer": { "type": "string", "const": "hekate" }, "signature_scheme": { "type": "string", "enum": ["ed25519.signer.v1", "hmac-sha256.beta.v1", "none.private_beta.v1"] }, "signer_id": { "type": "string" }, "signature_public_key": { "type": "string" }, "signature": { "type": "string" }, "claim_boundary": { "type": "string" } } }, "HekateLitePreflightResponse": { "type": "object", "properties": { "decision": { "type": "string", "enum": ["allow", "warn", "block"] }, "risk_score": { "type": "number" }, "risk_level": { "type": "string", "enum": ["low", "medium", "high", "critical"] }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/HekateFinding" } }, "reasons": { "type": "array", "items": { "type": "string" } }, "safe_call_policy": { "type": "object" }, "policy_patch": { "type": "object" }, "receipt_id": { "type": "string" }, "receipt": { "$ref": "#/components/schemas/HekateReceipt" }, "mode": { "type": "string", "const": "private_beta" }, "mainnet_certification": { "type": "string", "const": "not_certified" }, "payment_status": { "type": "string", "const": "not_enforced_private_beta" } } }, "MissionRequest": { "type": "object", "required": ["goal", "mission_type", "budget_usd"], "properties": { "goal": { "type": "string", "minLength": 3 }, "mission_type": { "type": "string", "enum": ["company_research", "competitor_research", "crypto_due_diligence", "market_research", "lead_enrichment"] }, "budget_usd": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "deadline_seconds": { "type": "integer", "minimum": 1 }, "output_format": { "type": "string", "enum": ["memo", "json", "markdown"] }, "org_id": { "type": "string" }, "agent_id": { "type": "string" }, "constraints": { "$ref": "#/components/schemas/MissionConstraints" } } }, "MissionConstraints": { "type": "object", "properties": { "freshness_days": { "type": "integer", "minimum": 1 }, "min_sources": { "type": "integer", "minimum": 1 }, "require_citations": { "type": "boolean" }, "blocked_categories": { "type": "array", "items": { "type": "string" } }, "allowed_data_sensitivity": { "type": "string", "enum": ["public", "internal", "confidential", "restricted"] }, "public_data_only": { "type": "boolean" } } }, "Mission": { "type": "object", "properties": { "mission_id": { "type": "string" }, "state": { "type": "string", "enum": ["created", "planned", "quoted", "policy_checked", "awaiting_approval", "executing", "verifying", "completed", "failed", "disputed", "refunded"] }, "request": { "$ref": "#/components/schemas/MissionRequest" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/MissionStep" } }, "total_cost_usd": { "type": "number" }, "confidence_score": { "type": "number", "minimum": 0, "maximum": 1 }, "result": {}, "audit_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "MissionStep": { "type": "object", "properties": { "step_id": { "type": "string" }, "step_type": { "type": "string", "enum": ["web_search", "company_data", "social_signals", "news", "verify_facts", "synthesize"] }, "required_capability": { "type": "string" }, "max_cost_usd": { "type": "number" }, "data_sensitivity": { "type": "string", "enum": ["public", "internal", "confidential", "restricted"] }, "verification_required": { "type": "boolean" }, "chosen_service_id": { "type": "string" }, "actual_cost_usd": { "type": "number" }, "receipt_id": { "type": "string" }, "output": {} } }, "RouteQuote": { "type": "object", "properties": { "mission_id": { "type": "string" }, "estimated_cost_usd": { "type": "number" }, "max_cost_usd": { "type": "number" }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/RouteCandidate" } }, "explanation": { "type": "string" } } }, "RouteCandidate": { "type": "object", "properties": { "step_id": { "type": "string" }, "service_id": { "type": "string" }, "estimated_cost_usd": { "type": "number" }, "score": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string" } } } }, "AuditEvent": { "type": "object", "properties": { "event_id": { "type": "string" }, "mission_id": { "type": "string" }, "actor_type": { "type": "string", "enum": ["user", "agent", "system", "policy_engine", "payment_executor", "verifier"] }, "actor_id": { "type": "string" }, "event_type": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "payload_hash": { "type": "string" }, "previous_event_hash": { "type": "string" }, "payload": { "type": "object" } } }, "AuditView": { "type": "object", "properties": { "mission_id": { "type": "string" }, "chain": { "oneOf": [ { "type": "object", "properties": { "ok": { "const": true } } }, { "type": "object", "properties": { "ok": { "const": false }, "brokenAt": { "type": "integer" } } } ] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } } } }, "Approval": { "type": "object", "properties": { "approval_id": { "type": "string" }, "mission_id": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "granted", "denied"] }, "created_at": { "type": "string", "format": "date-time" }, "decided_at": { "type": "string", "format": "date-time", "nullable": true } } }, "Dispute": { "type": "object", "properties": { "dispute_id": { "type": "string" }, "mission_id": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string", "enum": ["open", "denied", "refunded", "partial_refund"] }, "amount_disputed_usd": { "type": "number" }, "amount_refunded_usd": { "type": "number" }, "evidence_uri": { "type": "string", "nullable": true }, "receipt_id": { "type": "string", "nullable": true }, "resolution_note": { "type": "string", "nullable": true }, "opened_by": { "type": "string" }, "opened_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true } } }, "Webhook": { "type": "object", "properties": { "webhook_id": { "type": "string" }, "org_id": { "type": "string", "nullable": true }, "url": { "type": "string", "format": "uri" }, "secret": { "type": "string", "description": "HMAC-SHA256 secret. Returned ONCE on creation; not exposed afterwards." }, "event_types": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "MissionTemplate": { "type": "object", "properties": { "template_id": { "type": "string" }, "org_id": { "type": "string", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "request_template": { "$ref": "#/components/schemas/MissionRequest" }, "required_vars": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" } } }, "Provider": { "type": "object", "properties": { "provider_id": { "type": "string" }, "name": { "type": "string" }, "risk_score": { "type": "number" }, "certification_status": { "type": "string", "enum": ["none", "pending", "certified"] } } }, "ServiceEndpoint": { "type": "object", "properties": { "service_id": { "type": "string" }, "provider_id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "enum": ["search", "data", "inference", "media", "social", "infrastructure", "trading", "verification"] }, "description": { "type": "string" }, "endpoint_url": { "type": "string", "format": "uri" }, "http_method": { "type": "string", "enum": ["GET", "POST", "PUT", "DELETE"] }, "price_min_usd": { "type": "number" }, "price_max_usd": { "type": "number" }, "supported_networks": { "type": "array", "items": { "type": "string" } }, "tokens": { "type": "array", "items": { "type": "string" } }, "capabilities": { "type": "array", "items": { "type": "string" } } } }, "CertificationApplication": { "type": "object", "properties": { "application_id": { "type": "string" }, "provider_id": { "type": "string" }, "status": { "type": "string", "enum": ["submitted", "under_review", "approved", "rejected"] }, "criteria": { "type": "object", "properties": { "uptime_99_5_pct": { "type": "string", "enum": ["pending", "passing", "failing"] }, "schema_conformance": { "type": "string", "enum": ["pending", "passing", "failing"] }, "receipt_support": { "type": "string", "enum": ["pending", "passing", "failing"] }, "refund_sla": { "type": "string", "enum": ["pending", "passing", "failing"] }, "security_questionnaire": { "type": "string", "enum": ["pending", "passing", "failing"] } } }, "submitted_at": { "type": "string", "format": "date-time" }, "decided_at": { "type": "string", "format": "date-time", "nullable": true } } }, "BillingSummary": { "type": "object", "properties": { "org_id": { "type": "string", "nullable": true }, "month": { "type": "string", "example": "2026-05" }, "missions": { "type": "integer" }, "vendor_spend_usd": { "type": "number" }, "orchestration_fee_usd": { "type": "number" }, "total_usd": { "type": "number" } } }, "BillingEvent": { "type": "object", "properties": { "billing_event_id": { "type": "string" }, "mission_id": { "type": "string" }, "vendor_spend_usd": { "type": "number" }, "orchestration_fee_usd": { "type": "number" }, "applied_rate": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" } } }, "StatsOverview": { "type": "object", "properties": { "missions": { "type": "object", "properties": { "total": { "type": "integer" }, "by_state": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "spend": { "type": "object", "properties": { "last_7d_usd": { "type": "number" }, "last_7d_missions": { "type": "integer" }, "prev_7d_usd": { "type": "number" }, "change_pct": { "type": "number", "nullable": true }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "format": "date" }, "spend": { "type": "number" } } } } } }, "providers": { "type": "object", "properties": { "total": { "type": "integer" }, "certified": { "type": "integer" }, "pending": { "type": "integer" } } }, "recent": { "type": "array", "items": { "$ref": "#/components/schemas/Mission" } }, "activity": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } } } }, "KillSwitchStatus": { "type": "object", "properties": { "tripped": { "type": "boolean" }, "reason": { "type": "string", "nullable": true }, "tripped_at": { "type": "string", "format": "date-time", "nullable": true }, "tripped_by": { "type": "string", "nullable": true }, "env_locked": { "type": "boolean" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "reason": { "type": "string" }, "details": { "type": "object" } } } } }, "security": [{ "bearerAuth": [] }], "paths": { "/health": { "get": { "summary": "Liveness probe", "tags": ["stats"], "security": [], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "service": { "type": "string" }, "payment_mode": { "type": "string" } } } } } } } } }, "/v1/health": { "get": { "summary": "Hekate Lite public beta health and claim boundary", "tags": ["hekate-lite"], "security": [], "responses": { "200": { "description": "Hekate Lite status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" }, "mode": { "type": "string" }, "mainnet_certification": { "type": "string" }, "claim_boundary": { "type": "string" } } } } } } } } }, "/v1/receipts/signing-status": { "get": { "summary": "Inspect public Hekate receipt signing status without exposing secrets", "tags": ["hekate-lite"], "security": [], "responses": { "200": { "description": "Receipt signing status and next operator steps", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "signature_scheme": { "type": "string", "enum": ["ed25519.signer.v1", "hmac-sha256.beta.v1", "none.private_beta.v1"] }, "production_signature_available": { "type": "boolean" }, "portable_verification_ready": { "type": "boolean" }, "key_id": { "type": ["string", "null"] }, "signer_id": { "type": ["string", "null"] }, "public_key_fingerprint": { "type": "string" }, "trust_bundle": { "type": "string" }, "jwks": { "type": "string" }, "verify_endpoint": { "type": "string" }, "next_steps": { "type": "array", "items": { "type": "string" } }, "claim_boundary": { "type": "string" } } } } } } } } }, "/v1/agentsec/trust": { "get": { "summary": "Fetch Hekate receipt trust bundle", "tags": ["hekate-lite"], "security": [], "responses": { "200": { "description": "Trust material for AgentSec-compatible receipt verification", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string" }, "receipt_type": { "type": "string" }, "signature_scheme": { "type": "string" }, "keys": { "type": "array", "items": { "type": "object" } }, "claim_boundary": { "type": "string" } } } } } } } } }, "/.well-known/agentsec-jwks.json": { "get": { "summary": "Fetch Hekate receipt verifier keys as JWKS", "tags": ["hekate-lite"], "security": [], "responses": { "200": { "description": "JWKS verifier keys for portable receipt verification", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/v1/mcp/preflight": { "post": { "summary": "Run Hekate MCP/tool-surface preflight", "tags": ["hekate-lite"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mcp_manifest_url": { "type": "string", "format": "uri" }, "manifest": {}, "tools": { "type": "array", "items": { "type": "object" } }, "task": { "type": "string" }, "policy": { "type": "object" } } } } } }, "responses": { "200": { "description": "allow/warn/block with findings, safe-call policy, policy patch, and receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HekateLitePreflightResponse" } } } } } } }, "/v1/x402/preflight": { "post": { "summary": "Run Hekate x402 payment preflight", "tags": ["hekate-lite"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri" }, "payment_requirements": { "type": "object" }, "task": { "type": "string" }, "policy": { "type": "object" } } } } } }, "responses": { "200": { "description": "x402 allow/warn/block with price/network metadata and receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HekateLitePreflightResponse" } } } } } } }, "/v1/permissions/diff": { "post": { "summary": "Compare requested scopes to the declared task", "tags": ["hekate-lite"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["task", "requested_scopes"], "properties": { "task": { "type": "string" }, "requested_scopes": { "type": "array", "items": { "type": "string" } }, "policy": { "type": "object" } } } } } }, "responses": { "200": { "description": "scope minimization decision with excessive and minimal scopes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HekateLitePreflightResponse" } } } } } } }, "/v1/tool-chain/risk": { "post": { "summary": "Detect dangerous multi-tool paths", "tags": ["hekate-lite"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["tools"], "properties": { "tools": { "type": "array", "items": { "type": "object" } }, "policy": { "type": "object" } } } } } }, "responses": { "200": { "description": "tool-chain allow/warn/block with path evidence and receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HekateLitePreflightResponse" } } } } } } }, "/v1/receipts/verify": { "post": { "summary": "Verify an AgentSec-compatible Hekate receipt", "tags": ["hekate-lite"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["receipt"], "properties": { "receipt": { "$ref": "#/components/schemas/HekateReceipt" }, "evidence": {} } } } } }, "responses": { "200": { "description": "receipt verification result", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "issuer": { "type": "string" }, "subject": { "type": "string" }, "decision": { "type": "string", "enum": ["allow", "warn", "block"] }, "production_signature": { "type": "boolean" }, "claim_boundary": { "type": "string" } } } } } } } } }, "/v1/ergo/sage/preflight": { "post": { "summary": "Run Hekate preflight for a Sage quote", "tags": ["hekate-lite"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["sage_quote"], "properties": { "question": { "type": "string" }, "sage_quote": { "type": "object", "properties": { "price": { "type": "string" }, "rail": { "type": "string" }, "reserve_box_id": { "type": "string" }, "task_hash": { "type": "string" }, "deadline_blocks": { "type": "integer" }, "receipt_support": { "type": "boolean" } } }, "policy": { "type": "object", "properties": { "max_price_erg": { "type": "string" }, "allowed_rails": { "type": "array", "items": { "type": "string" } }, "require_full_receipt_bundle": { "type": "boolean" }, "mainnet_allowed": { "type": "boolean" } } } } } } } }, "responses": { "200": { "description": "Sage quote allow/warn/block with checks and receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HekateLitePreflightResponse" } } } } } } }, "/v1/ergo/note/check": { "post": { "summary": "Check an Ergo Note before trusting a paid-agent flow", "tags": ["hekate-lite"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["note"], "properties": { "note": { "type": "object", "properties": { "rail": { "type": "string" }, "reserve_box_id": { "type": "string" }, "task_hash": { "type": "string" }, "value_erg": { "type": "string" }, "price_erg": { "type": "string" }, "expiry_blocks": { "type": "integer" }, "status": { "type": "string" }, "settlement_tx": { "type": "string" } } }, "policy": { "type": "object" } } } } } }, "responses": { "200": { "description": "Ergo Note decision with status checks and receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HekateLitePreflightResponse" } } } } } } }, "/v1/ergo/sage/receipts/verify": { "post": { "summary": "Verify a Sage/Accord receipt bundle", "tags": ["hekate-lite"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agreement": { "type": "object" }, "verification_receipt": { "type": "object" }, "settlement_receipt": { "type": "object" }, "policy": { "type": "object" } } } } } }, "responses": { "200": { "description": "Receipt bundle completeness decision with Hekate security receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HekateLitePreflightResponse" } } } } } } }, "/v1/missions": { "post": { "summary": "Create a mission", "tags": ["missions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MissionRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mission" } } } }, "400": { "description": "Invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List missions (cursor pagination)", "tags": ["missions"], "parameters": [ { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "mission_type", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Mission" } }, "next_cursor": { "type": "string", "nullable": true } } } } } } } } }, "/v1/missions/{id}/quote": { "post": { "summary": "Plan + quote + preflight policy", "tags": ["missions"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "mission": { "$ref": "#/components/schemas/Mission" }, "quote": { "$ref": "#/components/schemas/RouteQuote" } } } } } }, "400": { "description": "Quote failed" } } } }, "/v1/missions/{id}/execute": { "post": { "summary": "Settle every step + verify + complete", "tags": ["missions"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mission" } } } } } } }, "/v1/missions/{id}/run": { "post": { "summary": "Convenience: quote + execute", "tags": ["missions"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mission" } } } } } } }, "/v1/missions/{id}": { "get": { "summary": "Get mission", "tags": ["missions"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mission" } } } }, "404": { "description": "Not found" } } } }, "/v1/missions/{id}/cancel": { "post": { "summary": "Cancel a mission (graceful — re-checked between steps)", "tags": ["missions"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["reason"], "properties": { "reason": { "type": "string", "minLength": 4 } } } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mission" } } } }, "409": { "description": "Cannot cancel terminal state" } } } }, "/v1/missions/{id}/audit": { "get": { "summary": "Hash-chained audit trail with chain integrity", "tags": ["missions"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditView" } } } } } } }, "/v1/missions/{id}/approvals": { "get": { "summary": "List pending approvals", "tags": ["missions"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Approval" } } } } } } } }, "/v1/missions/{id}/approvals/{approvalId}": { "post": { "summary": "Decide an approval", "tags": ["missions"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["decision"], "properties": { "decision": { "type": "string", "enum": ["granted", "denied"] } } } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } } } } }, "/v1/missions/{id}/disputes": { "post": { "summary": "Open a dispute on a completed mission", "tags": ["missions"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["reason", "amount_disputed_usd"], "properties": { "reason": { "type": "string" }, "amount_disputed_usd": { "type": "number" }, "evidence_uri": { "type": "string", "format": "uri" }, "receipt_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "mission": { "$ref": "#/components/schemas/Mission" }, "dispute": { "$ref": "#/components/schemas/Dispute" } } } } } } } }, "get": { "summary": "List disputes for a mission", "tags": ["missions"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Dispute" } } } } } } } }, "/v1/missions/{id}/disputes/{disputeId}/resolve": { "post": { "summary": "Resolve a dispute", "tags": ["missions"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "disputeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "enum": ["denied", "refunded", "partial_refund"] }, "amount_refunded_usd": { "type": "number" }, "resolution_note": { "type": "string" } } } } } }, "responses": { "200": { "description": "ok" } } } }, "/v1/templates": { "get": { "summary": "List mission templates", "tags": ["templates"], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MissionTemplate" } } } } } } }, "post": { "summary": "Create a mission template", "tags": ["templates"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "request_template"], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "request_template": { "$ref": "#/components/schemas/MissionRequest" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MissionTemplate" } } } } } } }, "/v1/templates/{id}/run": { "post": { "summary": "Run a mission from a template (substituting {{var}} placeholders)", "tags": ["templates"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vars": { "type": "object", "additionalProperties": { "type": "string" } }, "budget_usd": { "type": "number" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mission" } } } }, "400": { "description": "Missing vars or invalid" } } } }, "/v1/providers": { "get": { "summary": "List providers (requires provider:read)", "tags": ["providers"], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } } } } } } }, "post": { "summary": "Register a provider", "tags": ["providers"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["provider_id", "name"], "properties": { "provider_id": { "type": "string" }, "name": { "type": "string" }, "risk_score": { "type": "number" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" } } } } } } }, "/v1/providers/scorecard": { "get": { "summary": "Live quality scores for every registered provider (requires provider:read)", "tags": ["providers"], "responses": { "200": { "description": "ok" } } } }, "/v1/providers/{id}/score": { "get": { "summary": "Quality score + evidence for one provider (requires provider:read)", "tags": ["providers"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "ok" } } } }, "/v1/registry/status-history": { "get": { "summary": "Public registry status history", "tags": ["providers"], "responses": { "200": { "description": "mission_control.registry_status_history.v1 with ed25519.signer.v1 when the production signer is configured; otherwise none.private_beta.v1" } } } }, "/v1/providers/endpoints": { "get": { "summary": "List endpoints (filter by capability or provider_id; requires provider:read)", "tags": ["providers"], "parameters": [ { "name": "capability", "in": "query", "schema": { "type": "string" } }, { "name": "provider_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceEndpoint" } } } } } } }, "post": { "summary": "Register an x402 endpoint (provider:write; HTTPS URL without credentials/private IP)", "tags": ["providers"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceEndpoint" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceEndpoint" } } } } } } }, "/v1/certification/applications": { "post": { "summary": "Submit a certification application", "tags": ["certification"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["provider_id"], "properties": { "provider_id": { "type": "string" }, "notes": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificationApplication" } } } }, "409": { "description": "Provider already has an open application" } } }, "get": { "summary": "List certification applications (requires provider:read)", "tags": ["certification"], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["submitted", "under_review", "approved", "rejected"] } }, { "name": "provider_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CertificationApplication" } } } } } } } }, "/v1/certification/applications/{id}/criteria": { "post": { "summary": "Set a criterion status", "tags": ["certification"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["criterion", "status"], "properties": { "criterion": { "type": "string", "enum": ["uptime_99_5_pct", "schema_conformance", "receipt_support", "refund_sla", "security_questionnaire"] }, "status": { "type": "string", "enum": ["pending", "passing", "failing"] } } } } } }, "responses": { "200": { "description": "ok" } } } }, "/v1/certification/applications/{id}/decide": { "post": { "summary": "Approve or reject a certification application", "tags": ["certification"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "enum": ["approved", "rejected"] }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "ok" }, "400": { "description": "Approval blocked — failing criteria" } } } }, "/v1/billing/summary": { "get": { "summary": "Monthly orchestration + vendor spend summary", "tags": ["billing"], "parameters": [{ "name": "month", "in": "query", "schema": { "type": "string", "example": "2026-05" } }], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingSummary" } } } } } } }, "/v1/billing/events": { "get": { "summary": "Per-mission billing events", "tags": ["billing"], "parameters": [{ "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 1000 } }], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BillingEvent" } } } } } } } }, "/v1/billing/stripe-export": { "get": { "summary": "Stripe metered events ready to POST to billing/meter_events", "tags": ["billing"], "parameters": [ { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "map", "in": "query", "schema": { "type": "string", "example": "org_a:cus_AAA,org_b:cus_BBB" } } ], "responses": { "200": { "description": "ok" } } } }, "/v1/webhooks": { "post": { "summary": "Subscribe to events", "tags": ["webhooks"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["url", "event_types"], "properties": { "url": { "type": "string", "format": "uri" }, "event_types": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Created — secret returned ONCE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } } } }, "get": { "summary": "List subscribers", "tags": ["webhooks"], "responses": { "200": { "description": "ok" } } } }, "/v1/webhooks/{id}": { "delete": { "summary": "Disable a webhook", "tags": ["webhooks"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "204": { "description": "Disabled" } } } }, "/v1/webhooks/deliveries": { "get": { "summary": "List deliveries", "tags": ["webhooks"], "parameters": [ { "name": "webhook_id", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["pending", "succeeded", "failed", "dead"] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 500 } } ], "responses": { "200": { "description": "ok" } } } }, "/v1/webhooks/deliveries/{id}/replay": { "post": { "summary": "Replay a delivery (manual operator)", "tags": ["webhooks"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "ok" }, "404": { "description": "Not found" } } } }, "/v1/admin/kill-switch": { "get": { "summary": "Kill switch status", "tags": ["admin"], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KillSwitchStatus" } } } } } }, "post": { "summary": "Trip the kill switch — halts every paid call across the org", "tags": ["admin"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["reason"], "properties": { "reason": { "type": "string", "minLength": 4, "maxLength": 500 } } } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KillSwitchStatus" } } } } } }, "delete": { "summary": "Clear the runtime kill switch", "tags": ["admin"], "responses": { "200": { "description": "ok" }, "409": { "description": "Cannot clear — env-locked via MC_KILL_SWITCH=1" } } } }, "/v1/exports/missions.csv": { "get": { "summary": "Mission history (CSV)", "tags": ["exports"], "responses": { "200": { "description": "text/csv" } } } }, "/v1/exports/receipts.csv": { "get": { "summary": "Receipts (CSV)", "tags": ["exports"], "responses": { "200": { "description": "text/csv" } } } }, "/v1/missions/{id}/audit.csv": { "get": { "summary": "Audit trail (CSV)", "tags": ["exports"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "text/csv" }, "404": { "description": "Not found" } } } }, "/v1/stats/overview": { "get": { "summary": "Aggregated stats for dashboards", "tags": ["stats"], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsOverview" } } } } } } } } }