SpiderGate

The Studio API is the agent-callable half of the SpiderGate Studio. It manages projects (durable containers), sessions (conversations), assets (generated media attached to a project), and saved prompts (named bundles of system prompt, model, settings and reference media that the gateway expands server-side).

All routes are brand-scoped: the brand is resolved from your credential, and there is no cross-brand path.

Base URL and authentication


Base URL	`https://spideriq.ai/api/v1/gate/studio`
Auth	`Authorization: Bearer <client_id>:<api_key>:<api_secret>`
Also accepts	a dashboard session cookie, or a PAT (`spideriq_pat_…`)
Reads	any member of the brand
Writes	brand admin

A request with no credential returns 401. An account with no brand returns 409 rather than a 500.

curl -s https://spideriq.ai/api/v1/gate/studio/projects \
  -H "Authorization: Bearer $CLIENT_ID:$API_KEY:$API_SECRET"

Projects

A project is the container everything else hangs from. Deleting one cascades to its sessions and assets.

`POST /projects`

Create a project.

Parameter	Type	Required	Notes
`name`	string	yes	Display name

curl -s -X POST https://spideriq.ai/api/v1/gate/studio/projects \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "Caribbean Restaurant Outreach"}'

{
  "id": "e8ba9776-96a3-499d-bb62-7c281ffb3f66",
  "brands_id": 9,
  "name": "Caribbean Restaurant Outreach",
  "created_by": "cli_hm9o83p0e4t9rjd6",
  "created_at": "2026-08-10T08:19:41Z"
}

Returns 201.

`GET /projects`

List the brand's projects, newest-touched first, each with session_count and asset_count. Page with limit (1–200, default 50) and offset.

`GET /projects/{project_id}`

One project with its sessions and its asset gallery inlined. 404 if the project is not yours.

`PATCH /projects/{project_id}`

Rename. Body {"name": "…"}.

`DELETE /projects/{project_id}`

Delete the project and cascade to its sessions and assets. Returns 204.

Sessions

A session is one conversation. A session may carry no project, in which case the dashboard shows it as Scratch.

Method	Path	Purpose
`POST`	`/projects/{project_id}/sessions`	Open a conversation in a project (`201`)
`GET`	`/sessions`	List sessions
`GET`	`/sessions/{session_id}`	One session
`PATCH`	`/sessions/{session_id}`	Rename
`DELETE`	`/sessions/{session_id}`	Delete (`204`)

Per-message persistence is not part of this API. The composer holds messages client-side; a session records the conversation, not its turns.

Assets

An asset is a generated image, video or audio clip attached to a project. The record stores the media URL, not a copy of the bytes.

`POST /projects/{project_id}/assets`

Parameter	Type	Required	Notes
`media_url`	string	yes	The stored media URL
`kind`	string	yes	`image`, `video` or `audio`
`title`	string	no
`session_id`	uuid	no	Must belong to this project, else `422`
`meta`	object	no	Free-form; the dashboard stores the generation recipe here

Returns 201. DELETE /projects/{project_id}/assets/{asset_id} unlinks it (204).

Saved prompts

A saved prompt is {system_prompt, model, settings, reference_media_ids} under a name, inside a project.

`POST /projects/{project_id}/prompts`

Parameter	Type	Required	Notes
`name`	string	yes	1–255 chars. Unique within the project
`description`	string	no	≤ 4000 chars
`system_prompt`	string	no
`model`	string	no	A task alias or a concrete model id
`settings`	object	no	Saved values: temperature, aspect ratio, seed, voice
`reference_media_ids`	array	no	≤ 50 media ids or URLs

curl -s -X POST https://spideriq.ai/api/v1/gate/studio/projects/$PROJECT_ID/prompts \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "Venue Blurb",
    "system_prompt": "You write one-paragraph venue descriptions. Plain English, no superlatives.",
    "model": "spideriq/creative",
    "settings": {"temperature": 0.6, "max_tokens": 400}
  }'

{
  "id": "1ca17cb6-9911-4337-87b5-a8a7f36387b9",
  "public_id": "prompt_7382f72b9ee4014a5b23390ce2ed38c5",
  "project_id": "e8ba9776-96a3-499d-bb62-7c281ffb3f66",
  "name": "Venue Blurb",
  "model": "spideriq/creative",
  "settings": {"max_tokens": 400, "temperature": 0.6},
  "reference_media_ids": [],
  "last_used_at": null
}

Returns 201, or 409 if the name is already used in this project.

The rest of the prompt surface

Method	Path	Purpose
`GET`	`/projects/{project_id}/prompts`	List a project's prompts
`GET`	`/prompts?query=&project_id=`	Search brand-wide by name or description; omit `query` to list all
`GET`	`/prompts/{prompt_id}`	Get by `id` or `public_id`
`PATCH`	`/prompts/{prompt_id}`	Partial update. Sending `settings` or `reference_media_ids` REPLACES the stored value; it is not a deep merge
`DELETE`	`/prompts/{prompt_id}`	Delete (`204`)

Referencing a saved prompt

Put a reference in the prompt field of a chat or media-generation request and the gateway expands it before dispatch.

Form	Scope	Needs `project_id`
`prompt:<public_id>`	resolves anywhere in the brand	no
`prompt.<handle>`	resolves inside one project	yes

The handle is the prompt's name lowercased, with runs of non-alphanumeric characters collapsed to underscores and leading and trailing underscores stripped. Venue Blurb becomes venue_blurb. An exact name match always beats a slug match.

Overrides win. The stored system prompt, model, settings and reference media fill in only what your request did not set.

curl -s -X POST https://spideriq.ai/api/gate/v1/media/generations \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model": "fal/flux-dev", "params": {"prompt": "prompt:prompt_7382f72b9ee4014a5b23390ce2ed38c5"}}'

Reference errors

A value that parses as a reference and does not resolve is an error. A plain literal never raises one.

Status	`code`	When
`400`	`prompt_reference_needs_project`	`prompt.<handle>` sent without a `project_id`
`404`	`prompt_not_found`	No prompt with that id, or no name or handle match in the project
`409`	`prompt_reference_ambiguous`	A handle matching more than one prompt. The message names every candidate and nothing is chosen

Infrastructure failures degrade to the literal; only reference errors propagate.

Generating media as an agent

Two Bearer routes on the gateway base, https://spideriq.ai/api/gate/v1:

Method	Path	Purpose
`GET`	`/media/models`	The active media models and the parameters each one declares
`POST`	`/media/generations`	Generate. Body `{model, params}`; a saved-prompt reference goes in `params.prompt`

Read /media/models before you generate. Each model declares its own inputs, and a parameter that is not declared is dropped before the provider call. A declared parameter with a bad value returns 422 invalid_param naming the field and the accepted values.

Status	`code`	When
`422`	`invalid_param`	A declared parameter with a value outside its enum or range
`501`	`adapter_not_available`	An active model whose provider adapter is not registered
`503`	`model_not_available`	A model still marked `coming_soon`
`503`	`no_<provider>_key`	The brand has no key for that provider. Media keys are per-brand and never pooled
`504`	`generation_timeout`	The wall-clock cap expired (600s image and speech, 900s video)

A generation returns the stored media URL plus an est_cost breakdown showing the provider cost, the billed amount and whether the key was yours or ours.