A UUID is a small output, but Swarme's API treats it as a full capability run. You describe the slug, lock a quote, then run. Skipping a step is not a shortcut. It is a rejected request.
The public page is https://swarme.io/tool/uuid-generator. The machine path uses the same slug. This walkthrough is grounded in one completed quote-and-run: the returned value was 4cd3c7b6-0495-447a-8efd-9a1374f7599c, the price was $0.00 included, the quote lock was 900 seconds, and idempotency_required_for_client was true.
Get a key from the working developers tab
Create a scoped API key from the dashboard. The URL that works is https://swarme.io/dashboard?tab=developers. https://swarme.io/dashboard/developers returns 404.
Send Authorization: Bearer with only the scopes the job needs. For this tool, capabilities:read, capabilities:quote, and capabilities:run cover search through execution. Do not put a key in a URL, a frontend bundle, logs, or a repository.
Unauthenticated quote attempts fail. A login CSRF expiry surfaces the toast Your secure form token expired. Please go back and try again. An unauthenticated quote is HTTP 419. Treat both as "this request was not accepted as a machine client," not as a defect in UUID Generator.
Contract details live at https://swarme.io/developers. The documented sequence is Search, Describe, Quote, Run.
Describe the slug before you construct input
GET /api/capabilities/uuid-generator is the source of truth for fields, pricing, file requirements, and execution.machine_run_status. Read that status before quoting.
Canonical values are supported, requires_worker, plan_only, and describe_only. describe_only blocks quote and run. UUID Generator is supported. Most of the 1940-tool catalog is not. A directory listing is not an execution contract.
A search call is enough to find the slug:
GET /api/capabilities?q=uuid&limit=10
Then describe the selected slug. Empty input {} is valid for this generator. Other tools are not this tolerant; their 422 bodies name the missing field rule.
Quote even when the listed price is $0.00
POST /api/capabilities/uuid-generator/quote with the same input you will run and "client_type": "api".
The completed run was priced $0.00 included. The quote was still required. The lock lasted 900 seconds. Save quote_id and run inside that window. A quote is a lock on price, input, and permission, not a receipt written after execution.
Wallet balance can read $0.00 with billing mode metered_observe while an included tool still quotes and runs. Dashboard Lifetime can still show a $0 wallet. Included is not the same as "skip quote."
If you wait more than 900 seconds, quote again. Do not send an expired quote_id to run.
Run with the quote_id and a unique idempotency key
POST /api/capabilities/uuid-generator/run with:
- the same input used at quote
- quote_id
- "client_type": "api"
- an Idempotency-Key header
idempotency_required_for_client was true on the completed run. Use one stable key per logical attempt. Replays return the original work. A new key with different input is a different attempt.
Poll GET /api/capability-runs/{run_id} until the state is completed, failed, or cancelled. Documented intermediate states also include queued, running, and retrying. Do not treat a queued payload as a UUID. For this tool the completed output contained UUID 4cd3c7b6-0495-447a-8efd-9a1374f7599c.
export SWARME_API_KEY="YOUR_SWARME_API_KEY" export SWARME_BASE_URL="https://swarme.io" 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"}'
Those placeholders are the documented shape. They are not credentials.
What can still fail after a good quote
Quote success is not run success. Observed 422 responses on other supported tools, after a successful quote, include:
- Use labeled address lines in key: value form or provide JSON.
- Domain must contain valid ASCII hostname labels.
- backlinks must contain between 1 and 1,000 records.
- Enter valid Base64URL input.
UUID Generator accepted empty input. Other slugs need values that match the describe schema. Read the 422 body. It is usually a field rule, not an auth failure.
A short checklist
- Open https://swarme.io/dashboard?tab=developers and create a key. Do not use /dashboard/developers.
- Search, then GET /api/capabilities/uuid-generator.
- Confirm machine_run_status is not describe_only.
- Quote. Store quote_id. Note the 900-second lock and the $0.00 included price.
- Run with the same input, the quote ID, and an idempotency key.
- Poll until completed. Record the UUID. The observed value from the completed run was 4cd3c7b6-0495-447a-8efd-9a1374f7599c.
The same contract is documented for REST and MCP. For turning a larger request into a bounded operation, see AI tool routing. If the next step is a file upload rather than a UUID, review how to choose a secure online file tool before sending bytes.