The quote step is not a receipt written after work finishes. It is a lock on price, input, and permission that must exist before Swarme will accept run. That rule held on a completed uuid-generator call priced $0.00 included. The lock lasted 900 seconds. Run still required quote_id.

If you POST run without a live quote, you are skipping the control the API is built around. Docs at https://swarme.io/developers list the core flow as Bincike, Describe, Quote, Run. The quote line is not marked optional for included tools.

What the quote actually locks

A quote is bound zuwa:

  • the capability slug
  • the input you sent
  • the price or included policy at that moment
  • a quote_id you must pass zuwa run
  • a lifetime of 900 seconds

Send the same input on run that you sent on quote. A different payload is a different job. The UUID Mai ƙirƙira Shafi at https://swarme.io/kayan aiki/uuid-generator accepted empty input {} and still required the quote.

idempotency_required_for_client was true on the completed UUID run. Idempotency is a second control, not a substitute for quote_id. One stable Idempotency-Key per logical attempt. Replays return the original work. A new key with different input is a new attempt.

Included does not mean skip quote

The completed UUID run returned 4cd3c7b6-0495-447a-8efd-9a1374f7599c at $0.00 included. Wallet balance on the same account read $0.00 with billing mode metered_observe. Dashboard Lifetime still showed a $0 wallet.

Those readings did not waive quote. They also did not mean paid work would clear. Wallet or spend-limit failures are hard stops on paid runs. Included tools still quote so the client has a quote_id, a lock clock, and a price Filin zuwa surface before execution.

If you wait more than 900 seconds, quote again. Do not cache a quote_id across a deploy, a retry loop, or a lunch break.

Auth failures are not quote failures

Ƙirƙira keys at https://swarme.io/dashboard?tab=developers. /dashboard/developers returns 404.

An unauthenticated quote is HTTP 419. A login CSRF expiry surfaces Your secure Fom token expired. Please go back and try again. Neither message is a statement about UUID validity. Both mean the request was not accepted as an authenticated machine client.

Use Authorization: Bearer with capabilities:quote and capabilities:run. Do not put the key in a query string.

Quote can succeed while run still returns 422

Quote checks price, wallet policy, and that the capability is allowed zuwa proceed. It does not promise that every Filin will pass execution rules.

Observed supported tools quoted, then failed run with HTTP 422:

  • address-label-formatter: Use labeled address lines in key: value Fom or provide JSON.
  • apache-virtual-host-generator: Domain must contain valid ASCII hostname labels.
  • backlink-quality-checklist: backlinks must contain between 1 and 1,000 records.
  • base64-url-decoder: Enter valid Base64URL input.

Those strings are Filin rules from describe. Fix the input, quote again if the lock expired, and run. Do not treat 422 as "the quote system is broken."

describe_only is a different stop. Docs state that describe_only blocks quote and run. 1491 of 1940 catalog tools currently carry that status. 439 are supported. 10 are requires_worker. Quote is not how you force a describe-only kayan aiki zuwa execute.

A client sequence that matches the lock

  1. Describe the slug. Read execution.machine_run_status. Stop on describe_only, missing, or unknown values.
  2. Check GET /api/account/balance before paid work. $0.00 / metered_observe is an observed wallet, not a reason zuwa skip quote.
  3. POST quote with the exact input and "client_type": "api".
  4. Persist quote_id, the 900-second lock, and the price Filin ($0.00 included on the UUID run).
  5. Surface the price or policy failure zuwa the caller. Do not hide a hard stop.
  6. POST run with the same input, quote_id, and an Idempotency-Key.
  7. Poll GET /api/capability-runs/{run_id}. Handle completed, failed, and 422 bodies as separate outcomes.

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"}'

Pass the returned quote_id into run inside 900 seconds. The completed included run still followed that path.

Why the extra round trip exists

Without a quote, a client cannot show a price, cannot prove wallet clearance, and cannot bind the input that will actually execute. With a quote, the user (or the agent) sees the charge or the included policy before work starts.

That boundary matters more as soon as the job is a Fayil, a metered model, or a paid allowance. Confirmation should show the selected capability, relevant parameters, and expected charge or credit use. The UUID case is the minimum version of the same rule: even $0.00 included still quotes.

For how a router should pause before consequential execution, see AI kayan aiki routing. For what zuwa inspect before a Fayil leaves your machine, see how zuwa choose a secure kan layi Fayil kayan aiki.