# API changelog

> HTML version: https://storeshot.art/docs/changelog/

Versions of the StoreShot API contract (`https://api.storeshot.art/v1`, `info.version` of the
OpenAPI document), newest first. Every version so far is additive: existing requests, fields and
error codes keep working.

## 1.18.0 — 2026-11-03

- Added styles (brand kits): `POST /styles` (send an `Idempotency-Key`), `GET /styles`,
  `GET /styles/{id}`, `PATCH /styles/{id}` and `DELETE /styles/{id}`. A style holds a name, up to 8
  colours, a logo (copied from an upload), a background mood, a short background description and a
  caption tone, and can copy its colours and choices from a succeeded generation
  (`referenceGenerationId`). Styles are free; at most 50 per account (`403 FORBIDDEN`,
  `details.reason` `style_limit_reached`).
- Added optional `styleId` when creating a generation or a screenshot set (also with
  `?dryRun=true`): the style fills the palette and logo you leave out and adds its background mood,
  description and caption tone. Fields you send win. The style is copied into the generation or set
  when it is created, so editing or deleting the style later never changes it or its retries.
- Generations and screenshot sets have an optional `style` (`{ id, name, applied }`; `null` when no
  style was used, `id` `null` once the style is deleted).

## 1.17.0 — 2026-11-02

- Added device authorization (RFC 8628) so an agent without a key can get one with its human's
  approval: `POST /auth/device` returns a user code and a console link, and
  `POST /auth/device/token` returns a new API key once the human approves it in the developer
  console. Neither needs a credential.
- `POST /auth/device/token` answers refusals with the OAuth error body
  `{ "error", "error_description" }` (HTTP 400), not the usual error envelope.
- Both answer 404 `NOT_FOUND` while device authorization is turned off on the server.

## 1.16.0 — 2026-11-02

- The API description now starts with a "For AI agents" section: the usual workflow (check the
  key, upload, quote, create, poll, download), what costs credits and how to handle errors.
- Every operation description now ends with what it costs in credits and, for the main
  operations, when to use it. The code samples in the description use `STORESHOT_API_KEY`, like
  the guides.
- Text only: no request, response, header or error code changed.

## 1.15.0 — 2026-10-29

- Added projects: `POST /projects`, `GET /projects`, `GET`, `PATCH` and `DELETE /projects/{id}`,
  and `POST /projects/{id}/items` and `/items/remove` to group generations and screenshot sets.
- Added optional `projectId` when creating a generation or a screenshot set, and `?projectId=`
  (`none` for no project) and `?source=` filters on the lists.
- Generations and screenshot sets now show `source` (`api`, `web`, `mcp`, `cli` or `mobile`);
  generations also show `clientName`, `requestId` and `project`.
- Added `GET /activity`: who changed keys, credits and webhooks in the account.

## 1.14.0 — 2026-10-29

- Added `GET /status`: a public, cached summary of the API and generation pipeline status.

## 1.13.0 — 2026-10-29

- Added the Google Play device `google_play_1080x2160` (2:1).
- Deprecated `google_play_1080x2400` (`deprecated: true`, `replacedBy`); it is still accepted but
  is never a default.

## 1.12.0 — 2026-10-24

- Added an optional `preview` thumbnail to screenshot sets in `GET /screenshot-sets` and
  `GET /screenshot-sets/{id}`.

## 1.11.0 — 2026-10-23

- `GET /billing/checkouts/{id}` also accepts the payment provider's checkout id; plan checkouts
  add optional `planName` and `subscriptionStatus`.
- Added the `environment` filter to the generation and screenshot-set lists and the `status`
  filter to the screenshot-set list.

## 1.10.0 — 2026-10-22

- Added monthly plans: `GET /billing/plans`, `GET /billing/subscription`,
  `POST /billing/subscription/checkout`, `/change`, `/cancel` and `/uncancel`, and
  `POST /billing/portal`.
- Added the error code `BILLING_STATE_CONFLICT`. Rate and generation limits now follow the plan.

## 1.9.0 — 2026-10-22

- Added credit packs: `GET /billing/packs`, `POST /billing/checkout` and
  `GET /billing/checkouts/{id}`.
- Added the scopes `billing:read` and `billing:write` and the error code `BILLING_UNAVAILABLE`.

## 1.8.0 — 2026-10-22

- Added webhooks: `POST` and `GET /webhooks`, `GET`, `PATCH` and `DELETE /webhooks/{id}`,
  `POST /webhooks/{id}/rotate-secret`, `POST /webhooks/{id}/test` and
  `GET /webhooks/{id}/deliveries`.
- Added the events `generation.succeeded`, `generation.failed`, `screenshot_set.completed`,
  `credits.low` and `webhook.test`, the scopes `webhooks:read` and `webhooks:write`, and the error
  codes `WEBHOOK_URL_REJECTED` and `WEBHOOK_STATE_CONFLICT`.

## 1.7.0 — 2026-10-22

- Added screenshot sets: `POST /screenshot-sets` (with `?dryRun=true` to quote it),
  `GET /screenshot-sets`, `GET` and `DELETE /screenshot-sets/{id}`, `POST /screenshot-sets/{id}/retry`
  and `/cancel`, and `GET /screenshot-sets/{id}/archive` (`?layout=fastlane`).
- Generations of a set show `screenshotSet`; added the `?screenshotSetId=` filter and the error code
  `SCREENSHOT_SET_STATE_CONFLICT`.

## 1.6.0 — 2026-10-22

- Added `POST /palettes` (brand palettes from your images), `GET /stores` and
  `GET /stores/{store}/requirements` (official screenshot rules per store).

## 1.5.0 — 2026-10-22

- Added generations: `POST /generations`, `GET /generations`, `GET` and `DELETE /generations/{id}`
  and `POST /generations/{id}/cancel`, with `Prefer: wait` and `Idempotency-Key`.
- Added the error codes `IDEMPOTENCY_CONFLICT` and `GENERATION_STATE_CONFLICT`;
  `402 INSUFFICIENT_CREDITS` carries `details.topUpUrl`.

## 1.4.0 — 2026-10-21

- Added uploads: `POST /uploads` (multipart or `{ "url" }`), `POST /uploads/presign` and
  `POST /uploads/{id}/complete`, `GET /uploads`, `GET` and `DELETE /uploads/{id}`.
- Added the error codes `UPLOAD_NOT_READY` and `URL_FETCH_FAILED`; `UNSUPPORTED_FORMAT` and
  `IMAGE_TOO_LARGE` apply to uploads.

## 1.3.0 — 2026-10-21

- Added rate limits: `RateLimit` and `RateLimit-Policy` headers, `429 RATE_LIMITED` with
  `Retry-After`, and `429 CONCURRENCY_LIMITED` for too many generations in progress.

## 1.2.0 — 2026-10-21

- Added `GET /credits` and `GET /usage` (scope `usage:read`) and the optional
  `X-Storeshot-Client` header that labels your usage.

## 1.1.0 — 2026-10-21

- Added API keys (`ss_live_…`, `ss_test_…`) with scopes: `GET /me`, `POST` and `GET /api-keys`,
  and `DELETE /api-keys/{id}`.

## 1.0.0 — 2026-10-21

- First contract: `GET /health`, `GET /devices`, the OpenAPI document, the error envelope with its
  code catalogue and the `X-Request-Id` header.