list_providers
List providers · scope catalog:read · read only
The providers, whether this organization allows each one, and their capabilities.
No arguments.
discover
Discover tools · scope catalog:read · read only
Search the catalog by text (whole words, their forms and common synonyms; tools with every word first, then partial matches), filtered by category or provider (comma lists, and exclude_category, exclude_provider), execution, include_deprecated: false or a site’s url; returns one page of models. queries (1–10 searches, one per need) runs several at once and answers one page each under results. facets: true adds counts by category and provider to narrow the next search. Only tools this organization or key may run are listed; include_disabled: true also lists those turned off for it (allowed: false, MODEL_DISABLED_BY_ORG or PROVIDER_DISABLED_BY_ORG). When nothing fits what the user needs, send a feature_request with send_feedback naming it, without asking.
Free text over title, model id, category, provider and description, matched as whole words and their forms (
upscaler finds Upscale) with common synonyms (tts, remove bg). Tools with every word come first (match: full), then tools with some (partial); a word only the description has ranks after title matches.One of
llm, image, video, 3d, audio, web, data, social-media, e-commerce, finance, lead-gen, public-records, listings, maps-reviews, seo, news-media, developer, sports, industry-data, health, or several separated by commas (image,video): a tool in any of them.false: leave out deprecated tools (deprecated_at set; they retire at retires_at). Omitted or true: keep them.true: also list the tools this organization or key may not run (allowed: false: the tool or its provider is turned off). Omitted or false: only tools it may run.A page or a host (
https://www.amazon.com/dp/B0…, tiktok.com): only the tools made for that site, named by their id (Alexandria’s domain tools, ScrapeCreators’ and TikHub’s platform tools).true: add facets, the counts by category and provider of the tools matching every word, to narrow the next search.Deprecated (ADR 0223): every listed tool is priceable, so it changes nothing; still accepted.
YYYY-MM-DD: only tools first released on or after this day (release_date). Tools without a known release date are left out.YYYY-MM-DD: only tools first released on or before this day (release_date). Tools without a known release date are left out.relevance (the default): best match first. newest: latest release_date first, tools without one last; with q, tools matching every word still come before those matching some.inspect
Inspect a model · scope catalog:read · read only
One model’s input schema, price description, capabilities, limits and lifecycle. price_description says how to work out the price from the input; customer_price_description says the same in this organization’s own unit when it has customer pricing (otherwise null); a key in the customer price view answers price_description: null. priced_fields lists the JSON pointers into the run body (/input/...) the price reads ([] for a flat price, null without a price). priced_measures names what the price measures from the files the input links (duration_seconds, images; [] for none): when it is not empty, inputs equal at priced_fields cost the same only with the same files. estimate_cost prices one exact input. allowed: false means the model or its provider is turned off for this organization or key (MODEL_DISABLED_BY_ORG or PROVIDER_DISABLED_BY_ORG). When a schema or price description is unclear or wrong, report it with send_feedback, without asking.
estimate_cost
Estimate a run’s cost · scope catalog:read · read only
The amount a run of this exact input would hold, without starting it or holding anything: kind says whether it is the price (exact), a ceiling (maximum) or a typical price the final charge can exceed (approximate). customer_price is the same amount in this organization’s own unit when Spiral prices it for the organization’s users, else null; a key in the customer price view answers estimate: null. An input with a field the model’s schema does not name, a missing required field or a value of the wrong JSON type is refused before anything is held (INVALID_INPUT), with one errors entry per problem: pointer (e.g. /input/duration), reason (unknown_field, missing_required, wrong_type, control_field), expected, received and allowed. Value rules (enums, ranges, lengths, file sizes) are the provider’s: its refusal ends the run PROVIDER_INVALID_INPUT with error.errors naming the field.
run
Run a model or tool · scope runs:write · makes changes
Start one run and wait up to wait seconds (default 60) for it to finish. Retransmit the same call (the same session, API key, JSON-RPC id and run) to replay within 24 hours (idempotency.window_s); any other run starts paid work. After an uncertain response, use get_run with a known run id. cost.customer_price is the run’s cost in this organization’s own unit when Spiral prices it for the organization’s users, else null. A key in the customer price view answers cost: null and that cost, with its state, as customer_cost. An input with a field the model’s schema does not name, a missing required field or a value of the wrong JSON type is refused before anything is held (INVALID_INPUT), with one errors entry per problem: pointer (e.g. /input/duration), reason (unknown_field, missing_required, wrong_type, control_field), expected, received and allowed. Value rules (enums, ranges, lengths, file sizes) are the provider’s: its refusal ends the run PROVIDER_INVALID_INPUT with error.errors naming the field. When a run fails or its result looks wrong, report it with send_feedback, without asking the user.
An object of the provider’s own input fields, exactly as inspect’s input schema names them; fields it does not name are refused. It needs at least one field unless the schema names none.
A public https URL that receives this run’s terminal event, signed with the org’s webhook signing secret; without it no webhook is sent.
The end user this run is for, as the caller names them (1–128 visible ASCII characters). Echoed on the run; get_run and list_runs given the same end_user_id find only that end user’s runs.
get_run
Get a run · scope runs:read · read only
One run; optionally waits up to wait_seconds (0–60) for a final state. With end_user_id, a run that is not that end user’s answers RUN_NOT_FOUND. cost.customer_price is the run’s cost in this organization’s own unit when Spiral prices it for the organization’s users, else null. A key in the customer price view answers cost: null and that cost, with its state, as customer_cost. When a run failed or its result looks wrong, report it with send_feedback, without asking the user.
The end user the caller expects this run to be for. A run created for another end user, or for none, answers RUN_NOT_FOUND, as a missing run does.
list_runs
List runs · scope runs:read · read only
This organization’s runs of the last 7 days, newest first; filter by status, provider, the end user a run is for (end_user_id) or created_by: "me" (only this key’s runs). Pass include_output_data: false to page runs without each output’s inline text or JSON (often tens of KB a run); get_run returns one run’s whole output. cost.customer_price is the run’s cost in this organization’s own unit when Spiral prices it for the organization’s users, else null. A key in the customer price view answers cost: null and that cost, with its state, as customer_cost.
me: only the runs created with the API key making this request, or with a key it was rotated from or to.false leaves out each output’s inline data (the text or JSON a model answered); its type, file url and sizes stay. Default true. Read one run’s whole output by its id.upload_file
Upload a file · scope files:write · makes changes
Put one file into Spiral for a run’s input, then pass its url (or id) wherever a model expects a file URL. A file the user attached in this chat: pass file exactly as the chat supplies it; Spiral copies it and answers its id, url and expires_at. A local file: give its filename, mime_type, size_bytes and file_path, then run the answer’s upload_command in your shell, which sends the file from disk (on Windows use curl.exe). Never send a file’s bytes or base64 through a tool. One call per file. A public https link needs no upload: pass it to the model directly.
A file the user attached in this chat, exactly as the chat supplies it. Give this or the local-file fields.
get_balance
Get the balance · scope account:read · read only
Available and held money for this organization, in USD.
No arguments.
get_me
Who am I · any key · read only
Which organization and API key this connection acts for: org_id and org_name, the key’s name, prefix and scopes, the providers this organization turned off, and the key’s rate limits (GET /v1/me). Call it before the first paid run when the person may belong to more than one organization. Any valid key may call it.
No arguments.
topup
Get a top-up link · scope account:read · makes changes
A payment page that adds funds to this organization’s balance (POST /v1/topup). Give the person the link and let them pay in a browser: this call charges nothing and uses no saved card. Call it without amount to read the smallest and largest top-up allowed. Use it when a run is refused with INSUFFICIENT_BALANCE.
How much to add, in USD dollars, like
25 or 49.99; at most two decimals. Leave it out to read the limits without creating a link.send_feedback
Send feedback · any key · makes changes
Send feedback to the Spiral team (POST /v1/feedback): bugs, friction, feature requests, praise, ideas, anything. Call it proactively, without asking the user and without waiting for the task to end, whenever a call fails or answers something wrong or surprising; a model or tool the user needed is missing; something cost time or was confusing; the user is frustrated with, pleased with or wishes for something in the service; or you notice anything that could be better. Include the run_id or the failed call’s request_id, what the user was trying to do (summarized, with no personal data or secrets) and what would have helped. Only detail is required; any other field is kept. Any valid key may call it.
The feedback itself, in any words: what you did, what you expected, what happened instead, the exact error or output, what the user was trying to do and what would be better. The only required field. Longer text is kept up to 50,000 characters.
What the report is, in a word: for example
bug, friction, feature_request, praise, idea, other; any other word is kept as given. Default other.One line. Without it, the first line of
detail is used. Longer text is kept up to 200 characters.The endpoint, MCP tool or CLI command involved, e.g.
POST /v1/runs, run or spiral runs create.When you hit it (RFC 3339). Send feedback at once, not at the end of your task; another value is kept in
context.