{"openapi":"3.1.0","info":{"title":"Swarme Capability API","version":"2026-08-restoration-local","description":"Quote-first capability discovery, execution, upload, run-status and artifact contracts."},"servers":[{"url":"https://swarme.io"}],"paths":{"/api/capabilities":{"get":{"summary":"Search capabilities","responses":{"200":{"description":"Capability registry"}}}},"/api/capabilities/{slug}":{"get":{"summary":"Describe a capability","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Capability schema"}}}},"/api/capabilities/{slug}/quote":{"post":{"summary":"Quote a run","security":[{"SwarmeApiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Quote"}}}},"/api/capabilities/{slug}/run":{"post":{"summary":"Run or plan a capability","security":[{"SwarmeApiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Run"}}}},"/api/capabilities/crt/run":{"post":{"summary":"Run CRT","description":"Return bounded certificate-transparency observations for one registrable apex domain. The apex and returned observations are stored in capability_runs without an automatic TTL. Observations do not prove hosts are live.","security":[{"SwarmeApiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional for this free run. An 8-190 character stable key makes retries replay-safe.","schema":{"type":"string","minLength":8,"maxLength":190,"pattern":"^[A-Za-z0-9._:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrtRunRequest"}}}},"responses":{"200":{"description":"Completed CRT capability run envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrtRunResponse"}}}},"422":{"description":"Invalid envelope or CRT input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/capabilities/{slug}/upload-session":{"post":{"summary":"Reserve a private upload","security":[{"SwarmeApiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Upload session"}}}},"/api/capability-uploads/{upload_id}":{"put":{"summary":"Upload bytes","security":[{"SwarmeApiKey":[]}],"responses":{"200":{"description":"Stored upload"}}}},"/api/capability-runs/{run_id}":{"get":{"summary":"Read run status","security":[{"SwarmeApiKey":[]}],"responses":{"200":{"description":"Run status"}}}},"/api/capability-runs/{run_id}/artifacts":{"get":{"summary":"List run artifacts","security":[{"SwarmeApiKey":[]}],"responses":{"200":{"description":"Artifact manifest"}}}},"/api/capability-runs/{run_id}/cancel":{"post":{"summary":"Cancel an authorized queued run","security":[{"SwarmeApiKey":[]}],"responses":{"200":{"description":"Canonical cancelled run status"}}}},"/api/capability-runs/{run_id}/receipt":{"get":{"summary":"Read an authorized run receipt","security":[{"SwarmeApiKey":[]}],"responses":{"200":{"description":"Run and ledger receipt"}}}},"/api/account/balance":{"get":{"summary":"Read authorized wallet and spend controls","security":[{"SwarmeApiKey":[]}],"responses":{"200":{"description":"Account balance"}}}},"/api/account/usage-statement":{"get":{"summary":"Read an authorized usage statement","security":[{"SwarmeApiKey":[]}],"responses":{"200":{"description":"Usage statement"}}}},"/api/account/spend-diagnostics":{"get":{"summary":"Read authorized spend forecasting","security":[{"SwarmeApiKey":[]}],"responses":{"200":{"description":"Spend diagnostics"}}}},"/api/vault/profile":{"get":{"summary":"Read the authorized user Vault profile","security":[{"SwarmeApiKey":[]}],"responses":{"200":{"description":"Vault profile; vault:read scope required"}}}},"/api/vault/fields":{"get":{"summary":"List authorized Vault fields","security":[{"SwarmeApiKey":[]}],"responses":{"200":{"description":"Masked fields; vault:read scope required"}}},"post":{"summary":"Create or update a Vault field","security":[{"SwarmeApiKey":[]}],"responses":{"200":{"description":"Saved field; vault:write scope required"}}}},"/api/vault/extractions":{"get":{"summary":"List review-first Vault extractions","security":[{"SwarmeApiKey":[]}],"responses":{"200":{"description":"Extractions; vault:read scope required"}}},"post":{"summary":"Create review candidates","security":[{"SwarmeApiKey":[]}],"responses":{"200":{"description":"Pending extraction; vault:write scope required"}}}},"/api/vault/fill-document":{"post":{"summary":"Fill a private template using authorized Vault fields","security":[{"SwarmeApiKey":[]}],"responses":{"200":{"description":"Private document artifact; vault:fill scope required"}}}},"/mcp":{"post":{"summary":"MCP JSON-RPC endpoint","security":[{"SwarmeApiKey":[]}],"responses":{"200":{"description":"MCP response"}}}}},"components":{"securitySchemes":{"SwarmeApiKey":{"type":"http","scheme":"bearer","bearerFormat":"sk_sw_…"}},"schemas":{"CrtInput":{"type":"object","additionalProperties":false,"required":["apex"],"properties":{"apex":{"type":"string","format":"hostname","description":"Registrable eTLD+1 under the vendored PSL ICANN and PRIVATE sections; public suffixes and subdomains are rejected."},"include_first_seen":{"type":"boolean","default":false},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":100}}},"CrtRunRequest":{"type":"object","additionalProperties":false,"required":["input"],"properties":{"input":{"$ref":"#/components/schemas/CrtInput"},"quote_id":{"type":"string","format":"uuid","description":"Quote ID from the matching quote call. Optional for this free capability; a valid supplied UUID becomes the run ID."},"client_type":{"type":"string","minLength":2,"maxLength":24,"pattern":"^[A-Za-z0-9_-]+$","default":"api"}}},"CrtObservation":{"type":"object","additionalProperties":false,"required":["hostname"],"properties":{"hostname":{"type":"string","format":"hostname"},"first_seen":{"type":"string","format":"date-time"}}},"CrtResult":{"type":"object","additionalProperties":false,"required":["status","summary","apex","count","limit","include_first_seen","observations","provider","live_hosts_verified","disclosure"],"properties":{"status":{"type":"string","const":"completed"},"summary":{"type":"string"},"apex":{"type":"string","format":"hostname"},"count":{"type":"integer","minimum":0,"maximum":1000},"limit":{"type":"integer","minimum":1,"maximum":1000},"include_first_seen":{"type":"boolean"},"observations":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/CrtObservation"}},"provider":{"type":"string"},"live_hosts_verified":{"type":"boolean","const":false},"disclosure":{"type":"string"}}},"CrtRunResponse":{"oneOf":[{"$ref":"#/components/schemas/CrtCompletedRunResponse"},{"$ref":"#/components/schemas/CrtReplayRunResponse"}]},"CrtCompletedRunResponse":{"type":"object","additionalProperties":false,"required":["ok","run_id","status","quote","result"],"properties":{"ok":{"type":"boolean","const":true},"run_id":{"type":"string","format":"uuid"},"status":{"type":"string","const":"completed"},"quote":{"type":"object"},"result":{"$ref":"#/components/schemas/CrtResult"}}},"CrtReplayRunResponse":{"type":"object","required":["ok","run_id","status","idempotent_replay"],"properties":{"ok":{"type":"boolean","const":true},"run_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"idempotent_replay":{"type":"boolean","const":true},"quote":{"type":["object","null"]},"run":{"type":["object","null"]},"message":{"type":"string"}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string"}}}}}}