Studio

One message to Documents Studio's director — decks, proposals, résumés, invoices, one-pagers, reports — the same turn the app runs. Without artifact_id it opens a new document and writes it; with one it revises that document — a section, the look, or the whole thing. The director designs it and may add images. Usually 20–60 s, longer for long decks.

By default the director may first propose an outline or ask questions (status: "needs_input"). Reply "Build it" (or any go-ahead, or auto: true) to approve an outline, or answer the questions in another turn with the same artifact_id. auto: true skips all of that and writes immediately.

Put every fact, figure, name and date the document needs in message — the director uses only what you give it and the workspace's brand. Read the result with GET /v1/documents/{id}.

Example: { "message": "A 6-slide investor update for Q3: revenue $412k (+38% QoQ), 3 enterprise logos signed, runway 22 months, hiring 2 engineers.", "auto": true }

The answer (also what GET /v1/turns/{id} returns):

Send an Idempotency-Key header: a retry with the same key replays the turn instead of running (and charging) it twice. Once a turn has been claimed, a failure is answered as the turn with status: "failed" and an error; refusals before that (not found, no credits) are ordinary HTTP errors.

Slow: can take several minutes. Agents should send background: true and poll GET /v1/turns/{id} (tool studio_turn_get).

auto: true lets Attria decide instead of answering with status: "needs_input" (questions or an outline to confirm).

stream: true answers with Server-Sent Events; the last event is result (the same body a waiting call returns) or error.

background: true answers 202 Accepted at once with an id; poll GET /v1/turns/{id} (tool studio_turn_get) every 5–10 s until it finishes.

Send an Idempotency-Key header: a retry with the same key replays the first result instead of doing the work twice.

One message to Apps Studio's builder, the same turn the app runs. Without artifact_id it builds a new app on the workspace's own records (Objects) — screens, the data they read and write, and any Actions — compiles it and commits it; an app that has never been live is published so it appears in the workspace's Apps. With artifact_id it changes that app; a change to a live app stays a draft until someone publishes it in Studio. Usually 45–120 s.

Say what the app is for, who uses it, what it shows and what people do in it. The builder may ask questions (needs_input); auto: true makes it decide and build.

Example: { "message": "A job tracker for our crew: list open jobs by date, mark a job done, and add notes and photos to a job.", "auto": true }

The answer (also what GET /v1/turns/{id} returns):

Send an Idempotency-Key header: a retry with the same key replays the turn instead of running (and charging) it twice. Once a turn has been claimed, a failure is answered as the turn with status: "failed" and an error; refusals before that (not found, no credits) are ordinary HTTP errors.

Slow: can take several minutes. Agents should send background: true and poll GET /v1/turns/{id} (tool studio_turn_get).

auto: true lets Attria decide instead of answering with status: "needs_input" (questions or an outline to confirm).

stream: true answers with Server-Sent Events; the last event is result (the same body a waiting call returns) or error.

background: true answers 202 Accepted at once with an id; poll GET /v1/turns/{id} (tool studio_turn_get) every 5–10 s until it finishes.

Send an Idempotency-Key header: a retry with the same key replays the first result instead of doing the work twice.

One message to Images Studio's director, the same turn the app runs. Without artifact_id it opens a new board; with one (a board id from GET /v1/images/boards) it works on that board. When the director decides to make something it renders with the Studio's own pipeline (brand-aware planning, model routing, storage, metering) and the answer carries the finished images with their URLs. Usually 20–60 s. A question or chat is simply answered.

The director may ask questions (needs_input); auto: true makes it decide. Images are made at 4:5 by default — say another size or how many (1–4) in the message. For a precise operation (edit, remove background, reframe, upscale, product photo…) use POST /v1/studio/image/apps/{app} instead.

Example: { "message": "Two scroll-stopping images for a summer iced-latte promo, bright and minimal", "auto": true }

The answer (also what GET /v1/turns/{id} returns):

Send an Idempotency-Key header: a retry with the same key replays the turn instead of running (and charging) it twice. Once a turn has been claimed, a failure is answered as the turn with status: "failed" and an error; refusals before that (not found, no credits) are ordinary HTTP errors.

Slow: can take several minutes. Agents should send background: true and poll GET /v1/turns/{id} (tool studio_turn_get).

auto: true lets Attria decide instead of answering with status: "needs_input" (questions or an outline to confirm).

stream: true answers with Server-Sent Events; the last event is result (the same body a waiting call returns) or error.

background: true answers 202 Accepted at once with an id; poll GET /v1/turns/{id} (tool studio_turn_get) every 5–10 s until it finishes.

Send an Idempotency-Key header: a retry with the same key replays the first result instead of doing the work twice.

One message to Video Studio's director, the same turn the app runs: it edits a video project — trims, reorders, captions, titles, overlays, music placement — and the edits are applied and saved. Without artifact_id a new, empty vertical project is opened (the director can plan shots but there is no footage to edit yet). Usually 10–40 s.

Things the app would ask a person to confirm and pay for — filming an AI shot, a motion graphic, captions, finding clips — come back in video.pending_requests and are not run by this call; make them with POST /v1/studio/video/apps/{app}.

Example: { "artifact_id": "…", "message": "Tighten the intro to 3 seconds and add a title card that says 'Summer Sale'" }

The answer (also what GET /v1/turns/{id} returns):

Send an Idempotency-Key header: a retry with the same key replays the turn instead of running (and charging) it twice. Once a turn has been claimed, a failure is answered as the turn with status: "failed" and an error; refusals before that (not found, no credits) are ordinary HTTP errors.

Slow: can take several minutes. Agents should send background: true and poll GET /v1/turns/{id} (tool studio_turn_get).

auto: true lets Attria decide instead of answering with status: "needs_input" (questions or an outline to confirm).

stream: true answers with Server-Sent Events; the last event is result (the same body a waiting call returns) or error.

background: true answers 202 Accepted at once with an id; poll GET /v1/turns/{id} (tool studio_turn_get) every 5–10 s until it finishes.

Send an Idempotency-Key header: a retry with the same key replays the first result instead of doing the work twice.

The current state of a Studio turn — one started with background: true, or any earlier one. Same body as the turn's own answer. Poll it (every few seconds) while status is building; it ends as completed, needs_input or failed. For a new website, building lasts through the site's build (2–5 min) and job shows the stage.

Example: GET /v1/turns/5b7e2c8e-…

Every Content App in the Image and Video Studios — the same catalog as the Studio's Add menu — with what each one needs and whether it can be run over the API.

Use it to discover apps before calling POST /v1/studio/{studio}/apps/{app}. For each app you get its studio, id, label, description, examples, group and kind; runnable (and not_runnable_reason when it is false); what a run returns (assets, job, motion); its typical timing; and inputs, a JSON Schema of the request body that app accepts.

Free and instant.

Runs one Content App — the same render, model routing, storage and credit metering as the app's form in the Studio. List the apps and each one's exact inputs with GET /v1/studio/apps; send only the fields that app takes (others are rejected).

Image apps (/v1/studio/image/apps/{app}: generate, product-photo, ad-creative, edit, compose, variations, remove-background, reframe, upscale) answer when the images are saved — usually 20–90 seconds — with assets (id, url, width, height, …). Without board_id results go to the Library; apps that start from an image need board_id, and every source or reference asset must already be on that board. count defaults to 1.

Video apps (/v1/studio/video/apps/{app}: generate, product-ad, ugc-ad, recast, remake, avatar) film inside a video project (project_id). They answer in seconds with status: "building" (HTTP 202) and a job; the shot takes about 1–3 minutes. To check on it, repeat the same request with the same Idempotency-Key: the repeat reads the job and moves it forward, never starting or charging a second one. When status is complete, asset is the video. The shot is also added to the end of the project's video. generate without project_id instead makes one 8-second Library shot from prompt and answers when it is done (1–2 minutes).

Motion (/v1/studio/video/apps/motion) generates a designed animation as an editable Remotion composition, inside the request (1–4 minutes). status may be needs_input with motion.questions when the brief is ambiguous; send a more specific prompt.

Apps with runnable: false in the list (e.g. reference, camera-path, story, clips, music, sound-effect) answer 422 with the reason. Credits are reserved before a run and only what was made is charged; not enough credits is 402. Send an Idempotency-Key so a retry is charged once.

Example — POST /v1/studio/image/apps/product-photo:

{ "board_id": "6f1c…", "product_asset_id": "9a2e…", "product": "A matte black insulated travel mug", "direction": "Dawn café, soft window light, condensation detail", "aspect": "4:5" }

Example — POST /v1/studio/video/apps/generate:

{ "project_id": "c41d…", "prompt": "A close handheld shot of a runner tying bright red shoes before sunrise", "model": "standard", "seconds": 6 }

Slow: can take several minutes; keep the connection open (the server allows up to 800 s).

Send an Idempotency-Key header: a retry with the same key replays the first result instead of doing the work twice.

The websites made in Website Studio, most recently changed first.

status is the site's own state: draft (not built yet, or building), built (ready, not published), live (published at public_url), paused. For the build's progress fetch GET /v1/websites/{id}.

GET /v1/websites?limit=10

One website with its build status — poll this after a website turn answered building.

• build.status: building (queued or running; build.stage says which step), ready (built), failed (build.error says why), or not_started.
• status: the site itself — draft, built, live or paused. public_url is set while it is live.
• url opens it in Website Studio.

A new site usually builds in 2–5 minutes; an edit's rebuild in 1–3. Poll every 5–10 seconds.

GET /v1/websites/0c1d2e3f-…

The decks, proposals and documents made in Documents Studio, most recently changed first. Summaries only — fetch GET /v1/documents/{id} for the content.

kind is deck, proposal or document. public_url is set while the document is shared by link.

GET /v1/documents?limit=10

One document with its full structured content — what the Studio renders:

• content.layout — slides (a deck: one section per slide) or page (a scrolling document).
• content.theme — the look.
• content.sections[] — each with an id, an intent (cover, narrative, pricing, stats, …) and blocks[] (headings, text, lists, images, stats, pricing tables, buttons…).

To change it, send a turn with artifact_id set to this id (POST /v1/studio/document/turns).

GET /v1/documents/a3c2…

The workspace apps made in Apps Studio, most recently changed first.

live is true once a version has been published (it then appears in the workspace's Apps, at public_url, for signed-in members). version ahead of published_version means a change is waiting to be published.

GET /v1/apps

One app: its summary, its manifest (the Objects it reads and writes, with access, and the Actions it calls), and the paths of its source files.

To change it, send a turn with artifact_id set to this id (POST /v1/studio/app/turns).

GET /v1/apps/6e2f…

The boards in Images Studio, most recently changed first. A board is where a Studio image conversation happens and its images are kept; pass a board's id as artifact_id to POST /v1/studio/image/turns to keep working on it, or as board_id to GET /v1/images.

GET /v1/images/boards

Images in the workspace's Studio — made or uploaded — newest first, each with a URL you can download. Filter to one board with board_id (see GET /v1/images/boards).

GET /v1/images?board_id=b1f0…&limit=20

The video projects in Video Studio, most recently changed first: name, aspect, duration and poster. Pass a project's id as artifact_id to POST /v1/studio/video/turns to edit it with the director.

GET /v1/videos