AutoHDR

Returns the job's current state. Poll every 3–5s until `status` is `succeeded` or `failed` (typically ~30s–2min). Three terminal shapes: `succeeded` + an `output_image_version_uuid` = a new version was minted (download that); `succeeded` + null output = the model ran and chose to change nothing (no-op skip — common for camera_removal when no photographer is in frame; the photo is unchanged; confirm with `getPhotoHistory`); `failed` = it broke. Only the job's owner can read it. A terminal job stays queryable — a `succeeded`/`failed` job keeps returning its final state (and `failure_code`/`failure_message`), so missing the poll that first flips it loses nothing.

getTransformJob

Returns how a photo was made and every edit since, as a chain of steps (oldest first) — the same lineage the AutoHDR editor's history panel shows. Each step has a short `label`/`description` and points at its parent via `parent_image_version_uuid` (walk it to rebuild the chain; the `is_head` step is the current photo). Use step ids for branch edits on submit, or to deliver an earlier step (POST .../version to make it the head, then download); use the download endpoint for full-resolution files. Owned by the token identity; a photo you don't own returns 404.

getPhotoHistory

Returns `status` (`in_progress` | `success` | `failure`), `pipeline` (`hdr` | `display`), and the photo count. Poll every 3–5s while `in_progress`; stop at `success` (photos ready) or `failure`. `pipeline=hdr` is the photographer path (camera files) — the intended product, not 'HDR has started'. If `awaiting_files` is true, files have not been committed yet: call commit (retry on `files_not_landed`), do not treat this as a running HDR job. Display ingest is usually seconds. HDR typically takes a few minutes; plan on ~30 min, and large RAW sets can take up to an hour. `image_count` may climb while still `in_progress` — only `success`/`failure` are terminal. Do not submit transforms until `success` if you care which version is head. `pipeline=display` means the files were ingested as-is — no HDR. On `failure` you may optionally re-poll once after a few minutes — a very slow shoot can be flagged failed and then recover.

getPhotoshootStatus

The AI post-processing transforms partners may run, each with its live credit cost and whether it needs a mask. `style.credit_cost` is null: that edit is priced per model, on `style_credit_cost` from GET /v1/models. Do not treat a null or a missing number as 1. REST callers see the full catalog; MCP callers omit mask-required transforms (autoremove, autofill). Still requires a token like the rest of /v1. Fetch at runtime instead of hardcoding names or prices; new models appear here automatically.

listCapabilities

Models you can pass as `indoor_model_id` / `outdoor_model_id` at create: AutoHDR's own models, creator models like Aura, and your own or granted models. Interior photos use the indoor slot and exterior photos the outdoor slot; set both, since a slot you omit falls back to the account default. `variant` is `indoor`, `outdoor`, or `indoor/outdoor` (either). Indoor and outdoor versions of a look can share a name (Iris Blue Sky is 26 and 32), so pick by `id` and `variant`. All current creator models handle flash and flambient shoots; Aura, Fuse and Brut are built for it. `type=predefined` returns AutoHDR's own models (Iris, Ember, Classic); `type=custom` returns creator models like Aura plus your own and granted models, which depend on who the token acts for. `style_credit_cost` is what a `style` submit charges for that id; use it, not the `style` price on GET /v1/capabilities.

listModels

Returns a page of your transform jobs for one photoshoot, newest first. `photoshoot_id` is **required** — the list is always scoped to a single shoot (and to your token identity: you only ever see your own jobs). Use it to recover a lost `job_id` or reconcile a shoot's jobs without polling each by id. Filter by lifecycle bucket with `state` (`active` = in-flight/recent, `history` = older/terminal, `all` = both). Each row carries a `status_url` you can poll directly. To sweep every shoot, call `listPhotoshoots` and page this per id.

listTransformJobs

Returns each processed photo's ids and filename. Use it to pick photos, then call the download endpoint for full-resolution files. Photos come back in gallery order, the same order as the photoshoot on the AutoHDR site (walkthrough order when it's on), continuing across pages, so list position works as a sequence number when naming downloads. Paginated with `page`/`page_size` (same shape as the transforms list).

listPhotos

Returns the acting account's photoshoots created in the last 7 days (most recently created first), each with its address, processing status, and photo count. Use it to discover `photoshoot_id`s to poll, list photos, or download. The 7-day window is fixed and cannot be widened — shoots created earlier are not listed here, and every photoshoot endpoint answers them with 410 `photoshoot_expired`. Paginated with `page`/`page_size` (same shape as the other list endpoints).

listPhotoshoots

A page of the **public** preset catalog, newest first. Private (own/team) presets are not listed here — author and run those in the AutoHDR app. Each card carries a name, `creator_name`, what it outputs (`result_description`), its inputs (`input_ports` — what to supply, photo or video), example media, `credit_cost` per run, and `is_video`/`takes_clip`/`makes_clip`. `makes_clip` is true when the preset returns a video file. Otherwise it returns a photo. Both are AI edits (`takes_clip` only means the input is a clip). Get one by uuid with `getPreset`, then `runPreset`.

listPresets

List published AutoHDR skills: reviewed guides for real-estate tasks. Each has a name, a description, and what it declares it needs (script runtimes, network hosts, credentials). Read-only and free.

listSkills

Read one file of a published skill (a reference doc, example or script) by a path from getSkill's file list. Returns the text; reading a script does not run it. Read-only and free.

readSkillFile

⚠️ Spends credits (not idempotent — a retry re-charges). Run a preset on explicit photos (`items`) or every visible photo in one shoot (`photoshoot_id`) — provide exactly one. Supply any inputs the preset's `input_ports` ask for beyond the subject via `ports` (each a photo version in your listing or an s3:// upload from asset-uploads). Charges the preset's `credit_cost` per photo. `makes_clip` is true when the preset returns a video file. Otherwise it returns a photo. Both are AI edits. Returns one `workflow_uuid` per target — poll it with `getTransformJob`, then download. Video presets run on one target at a time (use `items`, not the whole-shoot path). 402 when out of credits.

runPreset

⚠️ Spends credits (not idempotent — a retry re-charges). Submit one AI post-processing transform against a processed photo. The output image is an AI edit. Address the photo by `photoshoot_id` + `image_uuid` + `image_version_uuid` — get all three from `GET /v1/photoshoots/{id}/photos` (there is no resubmit-by-image-alone path). `transform_name` must be one advertised by `/v1/capabilities`; `reedit` requires a `prompt`; `style` requires `model_id` (optional `prompt` only when that id is 25 or higher) and re-renders the photo's look from its original photos rather than stacking on the current edit; mask transforms require a `mask_url` (`autofill` also needs a `prompt` or `reference_image_urls`). Returns a job — poll `GET /v1/transforms/{job_id}` until `status` is `succeeded`/`failed` (typically ~30s–2min). Then fetch the result via the photos/download endpoints. Charges the catalog price on submit (see `/v1/capabilities`). For `style`, read `style_credit_cost` on the model from GET /v1/models — that is the price charged for the `model_id` you pass. Skipped or failed steps are refunded. 402 when the account is out of credits. `succeeded` with a null `output_image_version_uuid` means the model ran and chose to change nothing (a no-op skip) — the photo is unchanged.

submitTransform

Point a photo at one of its history versions (an `image_version_uuid` from GET .../history) so that step becomes the current version — the one download returns and future transforms build on. Free (no credits). Use it to deliver an earlier edit, e.g. the step before a later change, and after a `style` regenerate or a redo: those land beside the old version and don't become current on their own. The id must belong to this photo's history, otherwise 404; if an id from an earlier call 404s, read GET .../history again for the current ids.

setPhotoVersion

⚠️ Starts processing. Commit itself does not debit. House models = pay on download; creator models bill without download (fee when processing finishes). For `raw` this kicks off HDR and is not idempotent. Retry on error=files_not_landed; after 202 poll getPhotoshootStatus and ignore another commit 409. Call once every file has been PUT to its presigned URL (or, for from-urls, once you think the server fetch has landed). Pass the `job_id` from create in the body (it must belong to the photoshoot in the path — the two are cross-checked). Missing PUT files are 400. A from-urls job still landing is 409 `error=files_not_landed` — retry commit until 202. After 202, poll status; a later 409 `error=conflict` means already committed. Do not open another shoot.

commitPhotoshoot