Swarme

`GET /api/capabilities`searches by natural-language query and category. Describe the selected slug before constructing input: its schema is the source of truth for fields, pricing, file requirements, and execution support. - **Search**Find candidates with`?q=compress%20pdf`. - **Describe**Read`execution.machine_run_status`and the input schema. - **Quote**Confirm price, wallet clearance, and save the returned`quote_id`. - **Run**Send the same input, quote ID, and a unique idempotency key. ``` `export SWARME_API_KEY="YOUR_SWARME_API_KEY" export SWARME_BASE_URL="https://YOUR_SWARME_HOST" curl "$SWARME_BASE_URL/api/capabilities?q=compress%20pdf&limit=10" curl "$SWARME_BASE_URL/api/capabilities/compress-pdf" curl -X POST "$SWARME_BASE_URL/api/capabilities/uuid-generator/quote" \ -H "Authorization: Bearer $SWARME_API_KEY" -H "Content-Type: application/json" \ -d '{"input":{},"client_type":"api"}' curl -X POST "$SWARME_BASE_URL/api/capabilities/uuid-generator/run" \ -H "Authorization: Bearer $SWARME_API_KEY" \ -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" -H "Content-Type: application/json" \ -d '{"input":{},"client_type":"api","quote_id":"YOUR_QUOTE_ID"}'` ``` Create a scoped API key from[Dashboard → Developers. Send`Authorization: Bearer YOUR_SWARME_API_KEY`. Never put a key in client-side code, URLs, logs, or a repository. Use only the needed scopes:`capabilities:read`,`capabilities:quote`,`capabilities:run`,`uploads:write`,`artifacts:read`, and`billing:read`. Each client may have a USD cap. Check`GET /api/account/balance`before paid work; wallet or spend-limit failures are hard stops. Use one stable`Idempotency-Key`per logical quote/run attempt. Replays return the original work; a key cannot safely represent different input. Paid API runs may require it. Quote immediately before execution and pass its`quote_id`. Surface the price or policy failure to the user. Create a session for the selected slug, upload raw bytes to its returned URL with the dedicated token, then supply`upload_id`(or`upload_ids`) in quote and run input. Validate filename, MIME type, and size against describe. Never reuse or log an upload token. ``` `# Create a session. Keep its upload_token private. curl -X POST "$SWARME_BASE_URL/api/capabilities/compress-pdf/upload-session" \ -H "Authorization: Bearer $SWARME_API_KEY" -H "Content-Type: application/json" \ -d '{"input":{"filename":"document.pdf","content_type":"application/pdf","size_bytes":12345},"client_type":"api"}' # Read upload_url and upload_token from the response, then: curl -X PUT "YOUR_UPLOAD_URL" -H "Authorization: Bearer YOUR_UPLOAD_TOKEN" \ -H "Content-Type: application/pdf" --data-binary @document.pdf # Quote and run with upload_id; then poll /api/capability-runs/YOUR_RUN_ID.` ``` `GET /api/capability-runs/{run_id}`Read queued, running, retrying, completed, failed, or cancelled state.`POST /api/capability-runs/{run_id}/cancel`Cancel queued work or request cooperative cancellation.`GET /api/capability-runs/{run_id}/artifacts`List permission-checked artifacts, then follow their download links. The canonical values are`supported`,`requires_worker`,`plan_only`, and`describe_only`.`supported`executes in the declared mode.`requires_worker`preserves the worker-required response until that runtime is ready.`plan_only`returns a client plan without server processing.`describe_only`blocks quote/run. The legacy value`runnable`is accepted as`supported`for backward compatibility. Treat missing or unknown values as`describe_only`and re-describe before execution. Connect a streamable HTTP client to`https://swarme.io/mcp`. Begin with`tools/list`; do not assume a cached list. `swarme_capabilities_search``swarme_capability_describe``swarme_account_balance``swarme_tool_quote``swarme_tool_run``swarme_tool_status``swarme_tool_cancel``swarme_tool_artifacts``swarme_upload_session_create` Inspect`machine_run_status`after describe. Quote/run only`supported`,`requires_worker`, or`plan_only`; refuse`describe_only`, missing, and unknown values. Keep approval boundaries around paid runs and file access. ``` `{ "mcpServers": { "swarme": { "type": "streamable-http", "url": "https://YOUR_SWARME_HOST/mcp", "headers": { "Authorization": "Bearer ${SWARME_API_KEY}" } } } }` ``` ## Version and deprecate contracts explicitly. The](https://swarme.io/dashboard?tab=developers)[contract manifestinventories REST, MCP tools, execution and run states, quote/run and file lifecycles, errors, and scopes. The](https://swarme.io/contract-manifest.json)[machine-readable changelogclassifies changes as`additive`,`behavioral-risk`, or`breaking`. Unknown manifest elements fail compatibility checks conservatively. Run`php bin/check-contract-compatibility.php --baseline=BASELINE.json --candidate=CANDIDATE.json`locally or in CI. Breaking changes fail unless their stable change IDs appear in an explicit local approvals file. When deprecation is activated for an element, publish manifest`deprecated`metadata and use standard`Deprecation`,`Sunset`, and`Link: <...>; rel=deprecation`headers plus`Swarme-Contract-Version`. The configured target is at least 90 days' notice when practical. It is a governance target—not an SLA—and urgent security, legal, abuse-prevention, or uncontrollable upstream changes may require less notice. This increment configures and documents the convention only; it does not deprecate or remove any endpoint. These examples use environment variables and placeholders only. They contain no credentials. The source distribution also includes copyable, dependency-free`examples/rest-agent.php`and`examples/mcp-agent.php`recipes covering search through artifacts or cancellation, with an explicit`--approve`boundary and optional`--file=PATH`upload. Before integration, run`php bin/check-agent-contract.php`against bundled versioned fixtures. Supplying`--base-url=URL`is explicit and performs only read-only public discovery checks. These are reusable starter clients—not a generated SDK or a frozen SDK API. ``` `const baseUrl = process.env.SWARME_BASE_URL ?? "https://YOUR_SWARME_HOST"; const apiKey = process.env.SWARME_API_KEY; if (!apiKey) throw new Error("Set SWARME_API_KEY"); const request = async (path: string, init: RequestInit = {}) => { const response = await fetch(\`${baseUrl}${path}\`, { ...init, headers: { Authorization: \`Bearer ${apiKey}\`, "Content-Type": "application/json", ...init.headers }, }); if (!response.ok) throw new Error(\`${response.status}: ${await response.text()}\`); return response.json(); }; const described = await request("/api/capabilities/uuid-generator"); const rawStatus = described.capability?.execution?.machine_run_status; const machineStatus = rawStatus === "runnable" ? "supported" : rawStatus; const allowedStatuses = new Set(](https://swarme.io/contract-changelog.json)["supported", "requires_worker", "plan_only"]); if (!allowedStatuses.has(machineStatus)) throw new Error("Capability is describe-only; describe again before execution"); const quote = await request("/api/capabilities/uuid-generator/quote", { method: "POST", body: JSON.stringify({ input: {}, client_type: "api" }), }); const run = await request("/api/capabilities/uuid-generator/run", { method: "POST", headers: { "Idempotency-Key": crypto.randomUUID() }, body: JSON.stringify({ input: {}, client_type: "api", quote_id: quote.quote.quote_id }), }); const status = await request(\`/api/capability-runs/${run.run_id}\`);` ``` ``` `import os, uuid, requests base_url = os.getenv("SWARME_BASE_URL", "https://YOUR_SWARME_HOST") api_key = os.environ["SWARME_API_KEY"] headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"} described = requests.get(f"{base_url}/api/capabilities/uuid-generator", headers=headers, timeout=30).json() raw_status = described.get("capability", {}).get("execution", {}).get("machine_run_status") machine_status = "supported" if raw_status == "runnable" else raw_status if machine_status not in {"supported", "requires_worker", "plan_only"}: raise RuntimeError("Capability is describe-only; describe again before execution") quote = requests.post( f"{base_url}/api/capabilities/uuid-generator/quote", headers=headers, json={"input": {}, "client_type": "api"}, timeout=30, ).json() run = requests.post( f"{base_url}/api/capabilities/uuid-generator/run", headers={**headers, "Idempotency-Key": str(uuid.uuid4())}, json={"input": {}, "client_type": "api", "quote_id": quote["quote"]["quote_id"]}, timeout=30, ).json() status = requests.get(f"{base_url}/api/capability-runs/{run['run_id']}", headers=headers, timeout=30).json()` ``` This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases. Securely manage secrets and policies in HashiCorp Vault through an MCP interface. A RESTful API to programmatically interact with the Opal Security platform. ClawManager Fleet Control is a paid hosted remote MCP for ClawManager. It exposes Streamable HTTP tool calls, bearer-token access, public server-card metadata, usage logs, and receipt-orient Give your AI agents access to production without the risks of sharing SSH keys. A secure MCP gateway that acts as a proxy, providing authentication, tool discovery, caching, and guardrail enforcement. A feature-rich gateway and proxy that federates MCP and REST services, unifying discovery, authentication, rate-limiting, and observability into a single endpoint for AI clients. Network reconnaissance and security scanning with port scanning, DNS analysis, and vulnerability assessment A comprehensive MCP server for managing OPNsense firewalls, offering over 300 tools for configuration and monitoring. Manage OPNsense firewalls using Infrastructure as Code (IaC) principles. Security gateway for MCP servers — per-tool policies, Ed25519-signed receipts, human approval gates, and Cedar WASM policy engine.