StoreShot
Docs menu

API changelog

Every version of the StoreShot API contract, newest first.

View as Markdown

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.