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 搜索, Describe, Quote, Run. The quote line is not marked optional for included tools.
What the quote actually locks
A quote is bound 到:
- the capability slug
- the input you sent
- the price or included policy at that moment
- a quote_id you must pass 到 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 生成器 页面 at https://swarme.io/工具/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 字段 到 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
创建 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 表单 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 到 proceed. It does not promise that every 字段 will pass execution rules.
Observed supported tools quoted, then failed run with HTTP 422:
- address-label-formatter: Use labeled address lines in key: value 表单 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 字段 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 工具 到 execute.
A client sequence that matches the lock
- Describe the slug. Read execution.machine_run_status. Stop on describe_only, missing, or unknown values.
- Check GET /api/account/balance before paid work. $0.00 / metered_observe is an observed wallet, not a reason 到 skip quote.
- POST quote with the exact input and "client_type": "api".
- Persist quote_id, the 900-second lock, and the price 字段 ($0.00 included on the UUID run).
- Surface the price or policy failure 到 the caller. Do not hide a hard stop.
- POST run with the same input, quote_id, and an Idempotency-Key.
- 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 文件, 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 工具 routing. For what 到 inspect before a 文件 leaves your machine, see how 到 choose a secure 在线 文件 工具.