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 עמוד is https://swarme.io/כלי/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
צור 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 כלי, capabilities:read, capabilities:quote, and capabilities:run cover חיפוש 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 טופס 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 מחולל.
Contract details live at https://swarme.io/developers. The documented sequence is חיפוש, Describe, Quote, Run.
Describe the slug before you construct input
GET /api/capabilities/uuid-generator is the source of truth for שדות, pricing, קובץ requirements, and execution.machine_run_status. Read that status before quoting.
Canonical values are supported, requires_worker, תוכנית_only, and describe_only. describe_only blocks quote and run. UUID מחולל is supported. Most of the 1940-tool catalog is not. A directory listing is not an execution contract.
A חיפוש call is enough אל find the slug:
GET /api/capabilities?q=uuid&limit=10
Then describe the selected slug. Empty input {} is valid for this מחולל. Other tools are not this tolerant; their 422 bodies name the missing שדה 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 כלי 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 אל 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 כותרת עליונה
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 כלי 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 טופס or provide JSON.
- Domain must contain valid ASCII hostname labels.
- backlinks must contain between 1 and 1,000 records.
- Enter valid Base64URL input.
UUID מחולל accepted empty input. Other slugs need values that match the describe schema. Read the 422 body. It is usually a שדה rule, not an auth failure.
A short checklist
- Open https://swarme.io/dashboard?tab=developers and צור a key. Do not use /dashboard/developers.
- חיפוש, 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 כלי routing. If the next step is a קובץ העלאה rather than a UUID, review how אל choose a secure מקוון קובץ כלי before sending bytes.