Setup & Recipes API
Two read surfaces tell a caller where a workspace stands with its keys: the setup state (how far setup got, and the one next step) and the recipes (which ready-made spideriq/* names its keys can serve, slot by slot). The dashboard setup page and the recipe cards are built on these endpoints, and so are the agent tools.
If you are deciding whether to use them, read Set up SpiderGate with your own keys and Use recipes on your own keys first. This page is for the caller.
Base URL
https://spideriq.ai/api/v1Authentication
Send a bearer token for the workspace (a personal access token or the client_id:api_key:api_secret triple), or call from a signed-in dashboard session.
Authorization: Bearer $SPIDERIQ_TOKEN{brand_id} must be the workspace your credential belongs to. A brand you do not own answers 404, exactly as one that does not exist.
Endpoint summary
GET /brands/{brand_id}/gate/onboarding— member or the workspace's own agent · where setup stands and the next stepPATCH /brands/{brand_id}/gate/onboarding— member or the workspace's own agent · record answers, the step, skips or the statePOST /brands/{brand_id}/gate/onboarding/pool-consent— a signed-in workspace admin only · share free keys with the pool, or withdraw ·201GET /brands/{brand_id}/gate/recipes— member or the workspace's own agent · every recipe with each slot's state
No endpoint here ever returns a key value.
GET /brands/{brand_id}/gate/onboarding
Where setup stands for the workspace, what is connected, who you are waiting on, and the one next step with its links. Everything except the step, the answers, the skips and the caller's own dismissals is computed on this read, so it is never stale.
brand_id— integer · path · required · your workspace id
curl -s "https://spideriq.ai/api/v1/brands/$BRAND_ID/gate/onboarding" \
-H "Authorization: Bearer $SPIDERIQ_TOKEN"Response, for a workspace that has answered the first steps and holds no key yet (shortened):
{
"brand_id": 1234,
"state": "in_progress",
"step": 5,
"of": 6,
"step_label": "Add keys",
"answers": {"uses": {"goals": ["agents"], "agents": ["openclaw"], "other": null},
"pays_for": [], "free_keys_chosen": ["groq", "mistral"], "teammates": []},
"skipped_steps": [],
"connected": [],
"pool": {"entitled": false, "providers": []},
"waiting": [],
"can_use_models": false,
"models_usable": 0,
"models_total": 1524,
"recommended_model": null,
"pool_consent": {"state": null, "at": null},
"next": {"action": "add_key", "provider": "openai", "unlocks": 145,
"guide_url": "/docs/providers/openai",
"add_url": "https://app.spideriq.ai/dashboard/gate/setup?step=5&provider=openai"},
"completed_at": null
}::table
Field | Meaning
`state` | `in_progress` or `done`
`step` / `of` / `step_label` | The step the workspace is on, out of 6, and its name
`connected` | The providers this workspace can already use, and whose keys serve them (own, connected company, pool)
`pool.entitled` | `true` while the workspace shares at least one active free key, so it may use the community pool
`waiting` | Teammate invites still open, with the provider asked for and the hours left
`models_usable` / `models_total` | How many catalog models the workspace can call now, of how many
`next` | The one next step: an `action`, the `provider` it concerns, how many models it `unlocks`, and linksErrors: the status, its error.code, when it happens, and what to do.
Status | Code | When |
|---|---|---|
|
| No credential, or an invalid one |
|
| The brand is not yours, or does not exist |
| (none) | The state could not be read; retry |
PATCH /brands/{brand_id}/gate/onboarding
Record answers, the current step, skipped steps or the state. Send only the fields you change; the response is the new status, the same shape as the GET.
step— integer · 1 to 6state— string ·in_progressordoneanswers— object ·uses(goals,agents,other),pays_for,free_keys_chosen(provider names),teammates(proposals: email and providers)skipped_steps— array of integers · 1 to 6ui— object · a person's own dismissals of the setup bubble and the sign-in prompt · a token may not send it
curl -s -X PATCH "https://spideriq.ai/api/v1/brands/$BRAND_ID/gate/onboarding" \
-H "Authorization: Bearer $SPIDERIQ_TOKEN" \
-H "Content-Type: application/json" \
-d '{"step": 3, "answers": {"free_keys_chosen": ["groq", "mistral"]}}'Response: the full status, as in the GET above, with step: 3 and the new answers.
A teammate in answers.teammates is a proposal. It sends nothing. A workspace admin sends the invite from the dashboard.
Errors: the status, its error.code, when it happens, and what to do.
Status | Code | When |
|---|---|---|
|
| A token sent |
|
| The brand is not yours |
| (validation) | An unknown field, a step outside 1 to 6, an unknown provider, or a value the store refused |
| (none) | The setup store is not available yet; retry |
POST /brands/{brand_id}/gate/onboarding/pool-consent
Agree to share this workspace's free keys with the community pool, or withdraw. Each call is appended, never overwritten; a withdrawal takes the free keys out of the pool at once. Paid and subscription keys are never shared, whatever this says.
action— string · required ·consentorwithdrawtext_version— integer · optional · the version of the consent text the admin saw
curl -s -X POST "https://spideriq.ai/api/v1/brands/$BRAND_ID/gate/onboarding/pool-consent" \
-H "Cookie: __Secure-better-auth.session_token=$SESSION" \
-H "Content-Type: application/json" \
-d '{"action": "withdraw"}'Response 201: the recorded consent row, with its action and when it was made.
Errors: the status, its error.code, when it happens, and what to do.
Status | Code | When |
|---|---|---|
|
| Called with a bearer token. Sharing is agreed by a signed-in admin, never by a token |
| (none) | Signed in, but not an Admin of this workspace |
| (validation) |
|
| (none) | The setup store is not available yet; retry |
GET /brands/{brand_id}/gate/recipes
Every recipe (spideriq/chat, spideriq/coding, …) with each slot's state for this workspace, the recipe to recommend, and the providers that would unlock the most locked recipes.
brand_id— integer · path · required · your workspace id
curl -s "https://spideriq.ai/api/v1/brands/$BRAND_ID/gate/recipes" \
-H "Authorization: Bearer $SPIDERIQ_TOKEN"Response (shortened to one recipe):
{
"brand_id": 1234,
"recipes_active": true,
"pool_entitled": false,
"recommended": "spideriq/chat",
"usable": 12,
"total": 32,
"recipes": [
{
"name": "spideriq/chat",
"usable": true,
"filled_by": "own",
"recommended": true,
"slots": [
{"slot": 0, "rank": 0, "provider": "minimax", "model": "MiniMax-M3",
"state": "usable", "filled_by": "own", "integration_id": 101, "unlock": null},
{"slot": 1, "rank": 1, "provider": "mistral", "model": "codestral-2508",
"state": "locked", "filled_by": null, "integration_id": null,
"unlock": {"provider": "mistral", "add_method": "paste",
"guide_url": "/docs/providers/mistral",
"add_url": "https://app.spideriq.ai/dashboard/gate/setup?step=5&provider=mistral"}}
],
"unlock_providers": []
}
],
"unlock": [{"provider": "mistral", "opens_recipes": 9}]
}::table
Field | Meaning
`recipes_active` | `true` when recipes run on the workspace's own keys first
`slots[].state` | `usable`, `locked` (no key reaches this provider), `lease_only` (the provider runs through its own sign-in app, never through a recipe) or `not_routed` (never tried from this slot)
`slots[].filled_by` | `own`, `group` (a connected company's key) or `pool` (a community pool key)
`slots[].integration_id` | The id of your own key that fills the slot. Only for `own`
`slots[].unlock` | For a locked slot: the provider, how its key is added, and links
`unlock[]` | Providers ordered by how many locked recipes one key of theirs would openErrors: the status, its error.code, when it happens, and what to do.
Status | Code | When |
|---|---|---|
|
| No credential, or an invalid one |
|
| The brand is not yours, or does not exist |
| (none) | The recipes could not be read; retry |
From an agent or the command line
The same reads, with no brand id to pass (the credential names the workspace):
::table
Read | MCP tool (`@spideriq/mcp-gate`) | CLI (`@spideriq/cli`)
Setup state and the next step | `gate_onboarding_status` | `spideriq gate setup status`
Record answers, step or skips | `gate_onboarding_update` | (none)
Propose a teammate invite | `gate_invite_contributor` (proposes only; a person sends it) | (none)
Recipes, slot by slot | `gate_recipes` | `spideriq gate recipes [--usable]`Related
Errors —
403 no_accessis what a call to a locked recipe returnsClient Aliases API — aliases of your own, on your own keys