Schemas

The 117 objects of the StoreShot API 1.18.0 contract.

ApiKeyEnvironment

string

test keys never incur charges or call image providers.

One of: "live" , "test"

GenerationStatus

string

queued: waiting for a worker (can be canceled). running: being generated (retries keep it running). succeeded, failed and canceled are final.

One of: "queued" , "running" , "succeeded" , "failed" , "canceled"

StoreTarget

string

One of: "app_store" , "google_play"

Orientation

string

One of: "portrait" , "landscape"

PaletteColor

object

Field	Type	Description
`hex`required	`string`
`name`required	`string`

WebhookGenerationData

object

The Generation at the time of the event, without download URLs.

Field	Type	Description
`id`required	`string`	Format: uuid
`status`required	`GenerationStatus`
`environment`required	`ApiKeyEnvironment`
`inputs`required	`array of object`
`inputs[].uploadId`required	`string`	Format: uuid
`inputs[].sourceUrl`required	`string`nullable	For a URL input: origin and path of the URL (it was imported as `uploadId`).
`store`required	`StoreTarget`
`device`required	`string`	Catalogue id of the size.
`size`required	`object`
`size.width`required	`integer`
`size.height`required	`integer`
`orientation`required	`Orientation`
`app`required	`object`
`app.name`required	`string`
`app.description`required	`string`
`caption`required	`string`nullable	As requested; null = derive.
`palette`required	`array of PaletteColor`nullable	As requested, or from the style (`style.applied` contains `palette`); null = extract from the screenshot.
`logo`required	`object`nullable
`logo.uploadId`required	`string`	Format: uuid
`metadata`required	`object`
`creditsCharged`required	`integer`	1 for live keys, 0 for test keys.
`creditsRefunded`required	`integer`	Refunded when the generation failed or was canceled before it started.
`result`required	`object`nullable	As in `GET /generations/{id}` but without URLs (they expire): fetch the generation for fresh ones.
`result.image`required	`object`
`result.image.contentType`required	`string`	PNG; JPEG for the Google Play feature graphic.One of: "image/png", "image/jpeg"
`result.image.width`required	`integer`
`result.image.height`required	`integer`
`result.thumbnail`required	`object`nullable
`result.thumbnail.contentType`required	`string`	One of: "image/webp"
`result.caption`required	`string`	The caption used: yours, or the one derived from the screenshot (may be empty).
`result.palette`required	`array of PaletteColor`	The colours used.
`error`required	`object`nullable	Only when `failed`. See /v1/docs/errors for each code.
`error.code`required	`string`	One of: "GENERATION_FAILED", "GENERATION_TIMEOUT", "NOT_A_SCREENSHOT", "UPLOAD_NOT_READY", "INTERNAL_ERROR"
`error.message`required	`string`
`createdAt`required	`string`	RFC 3339 UTC timestamp.
`startedAt`required	`string`nullable	RFC 3339 UTC timestamp.
`finishedAt`required	`string`nullable	RFC 3339 UTC timestamp.
`deletedAt`required	`string`nullable	Set by `DELETE`: the result files are gone, this record stays.
`screenshotSet`	`object`	Present only when this generation is an image of a screenshot set (`POST /screenshot-sets`).
`screenshotSet.id`required	`string`	Format: uuid
`screenshotSet.position`required	`integer`	The screen (1-based).
`screenshotSet.attempt`required	`integer`	2 and up: a retry.

GenerationSucceededEvent

object

Field	Type	Description
`id`required	`string`	Event id (`evt_…`), identical on every attempt: deduplicate on it.
`type`required	`string`	One of: "generation.succeeded"
`created`required	`string`	RFC 3339 UTC timestamp.
`environment`required	`ApiKeyEnvironment`
`apiVersion`required	`string`
`data`required	`WebhookGenerationData`

GenerationFailedEvent

object

Field	Type	Description
`id`required	`string`	Event id (`evt_…`), identical on every attempt: deduplicate on it.
`type`required	`string`	One of: "generation.failed"
`created`required	`string`	RFC 3339 UTC timestamp.
`environment`required	`ApiKeyEnvironment`
`apiVersion`required	`string`
`data`required	`WebhookGenerationData`

ScreenshotSetStatus

string

Computed from the current image of every slot: queued (all queued), running (any running, or some finished and some not), succeeded (all succeeded), partially_failed (all finished, some succeeded), canceled (none succeeded, all canceled), failed (none succeeded, otherwise).

One of: "queued" , "running" , "succeeded" , "partially_failed" , "failed" , "canceled"

ScreenshotSetPreview

object

A thumbnail for lists (since 1.12.0): the most recently finished succeeded image of the current attempts, a device screenshot before the Google Play feature graphic. Only on GET /screenshot-sets and GET /screenshot-sets/{id}; absent from create, retry and cancel answers and from screenshot_set.completed events. null while no image has succeeded, or for a deleted set.

Field	Type	Description
`generationId`required	`string`	The image shown.Format: uuid
`store`required	`StoreTarget`
`device`required	`string`
`thumbnail`required	`object`
`thumbnail.url`required	`string`	Signed URL of the 512 px WebP preview (expires at `urlsExpireAt`).Format: uri
`thumbnail.contentType`required	`string`	One of: "image/webp"
`urlsExpireAt`required	`string`	15 minutes after this response. Fetch the set again for a fresh URL.

WebhookScreenshotSetData

object

The ScreenshotSet at the time of the event, without source, project and preview.

Field	Type	Description
`id`required	`string`	Format: uuid
`status`required	`ScreenshotSetStatus`
`environment`required	`ApiKeyEnvironment`
`app`required	`object`
`app.name`required	`string`
`app.description`required	`string`
`orientation`required	`Orientation`
`palette`required	`array of PaletteColor`	The palette of every image: as requested, or from the style (`style.applied` contains `palette`), or extracted.
`paletteSource`required	`string`	`auto`: extracted from screen 1 when the set was created.One of: "given", "auto"
`logo`required	`object`nullable
`logo.uploadId`required	`string`	Format: uuid
`metadata`required	`object`
`screens`required	`array of object`
`screens[].position`required	`integer`
`screens[].input`required	`object`
`screens[].input.uploadId`required	`string`	Format: uuid
`screens[].caption`required	`string`
`stores`required	`array of object`
`stores[].store`required	`StoreTarget`
`stores[].devices`required	`array of string`
`stores[].featureGraphic`required	`object`nullable
`stores[].featureGraphic.screen`required	`integer`
`stores[].featureGraphic.caption`required	`string`
`images`required	`integer`
`counts`required	`object`
`counts.queued`required	`integer`
`counts.running`required	`integer`
`counts.succeeded`required	`integer`
`counts.failed`required	`integer`
`counts.canceled`required	`integer`
`creditsCharged`required	`integer`	Every image of the set, retries included (0 with a test key).
`creditsRefunded`required	`integer`
`children`required	`array of object`	The current image of every slot (store, device, screen). Result URLs: `GET /generations?screenshotSetId=` or the archive.
`children[].position`required	`integer`	The screen (1-based).
`children[].store`required	`StoreTarget`
`children[].device`required	`string`
`children[].size`required	`object`
`children[].size.width`required	`integer`
`children[].size.height`required	`integer`
`children[].featureGraphic`required	`boolean`
`children[].generationId`required	`string`	Format: uuid
`children[].attempt`required	`integer`
`children[].status`required	`GenerationStatus`
`children[].error`required	`object`nullable
`children[].error.code`required	`string`	One of: "GENERATION_FAILED", "GENERATION_TIMEOUT", "NOT_A_SCREENSHOT", "UPLOAD_NOT_READY", "INTERNAL_ERROR"
`children[].error.message`required	`string`
`archiveUrl`required	`string`
`createdAt`required	`string`	RFC 3339 UTC timestamp.
`updatedAt`required	`string`	RFC 3339 UTC timestamp.
`finishedAt`required	`string`nullable	RFC 3339 UTC timestamp.
`deletedAt`required	`string`nullable	RFC 3339 UTC timestamp.
`preview`	`ScreenshotSetPreview`

ScreenshotSetCompletedEvent

object

Field	Type	Description
`id`required	`string`	Event id (`evt_…`), identical on every attempt: deduplicate on it.
`type`required	`string`	One of: "screenshot_set.completed"
`created`required	`string`	RFC 3339 UTC timestamp.
`environment`required	`ApiKeyEnvironment`
`apiVersion`required	`string`
`data`required	`WebhookScreenshotSetData`

CreditsLowEvent

object

Field	Type	Description
`id`required	`string`	Event id (`evt_…`), identical on every attempt: deduplicate on it.
`type`required	`string`	One of: "credits.low"
`created`required	`string`	RFC 3339 UTC timestamp.
`environment`required	`ApiKeyEnvironment`
`apiVersion`required	`string`
`data`required	`object`
`data.balances`required	`object`
`data.balances.starter`required	`integer`
`data.balances.subscription`required	`integer`
`data.balances.purchased`required	`integer`
`data.total`required	`integer`
`data.threshold`required	`integer`

WebhookTestEvent

object

Field	Type	Description
`id`required	`string`	Event id (`evt_…`), identical on every attempt: deduplicate on it.
`type`required	`string`	One of: "webhook.test"
`created`required	`string`	RFC 3339 UTC timestamp.
`environment`required	`ApiKeyEnvironment`
`apiVersion`required	`string`
`data`required	`object`
`data.webhookId`required	`string`	Format: uuid
`data.message`required	`string`

CheckStatus

string

One of: "up" , "down" , "not_configured"

HealthReport

object

Field	Type	Description
`status`required	`string`	One of: "healthy", "degraded"
`version`required	`string`	Server release version.
`commit`required	`string`	Deployed git commit (short SHA).
`checks`required	`object`
`checks.database`required	`CheckStatus`
`checks.redis`required	`CheckStatus`

ErrorCode

string

Stable, machine-readable error code. See /v1/docs/errors.

One of: "INVALID_INPUT" , "UNAUTHORIZED" , "FORBIDDEN" , "NOT_FOUND" , "METHOD_NOT_ALLOWED" , "PAYLOAD_TOO_LARGE" , "UPLOAD_NOT_READY" , "IDEMPOTENCY_CONFLICT" , "GENERATION_STATE_CONFLICT" , "SCREENSHOT_SET_STATE_CONFLICT" , "WEBHOOK_STATE_CONFLICT" , "BILLING_STATE_CONFLICT" , "IMAGE_TOO_LARGE" , "UNSUPPORTED_FORMAT" , "NOT_A_SCREENSHOT" , "URL_FETCH_FAILED" , "WEBHOOK_URL_REJECTED" , "INSUFFICIENT_CREDITS" , "RATE_LIMITED" , "CONCURRENCY_LIMITED" , "INTERNAL_ERROR" , "GENERATION_FAILED" , "SERVICE_UNAVAILABLE" , "BILLING_UNAVAILABLE" , "GENERATION_TIMEOUT"

ErrorEnvelope

object

Field	Type	Description
`error`required	`object`
`error.code`required	`ErrorCode`
`error.message`required	`string`	Human-readable message; safe to display.
`error.requestId`required	`string`	Equals the X-Request-Id response header.
`error.docUrl`required	`string`	Documentation for this error code.Format: uri
`error.details`	`object`	Code-specific structured details.

DeviceKind

string

One of: "screenshot" , "feature_graphic"

Device

object

Field	Type	Description
`id`required	`string`	Stable identifier: `<store>_<width>x<height>`.
`store`required	`StoreTarget`
`kind`required	`DeviceKind`
`label`required	`string`	Display name; may change. Do not parse.
`deviceHint`required	`string`	Example devices; may change. Do not parse.
`width`required	`integer`	Pixels. Portrait (canonical) for screenshots; landscape swaps width/height.
`height`required	`integer`	Pixels.
`orientations`required	`array of Orientation`
`deprecated`	`boolean`	`true`: still accepted (same output size) so existing requests keep working, but it breaks a store rule or is superseded. Never a default. Use `replacedBy`. Absent otherwise.
`replacedBy`	`string`	Deprecated devices only: the `GET /devices` id to use instead.

DeviceList

object

Field	Type	Description
`data`required	`array of Device`

ComponentStatus

string

The worst known component state (unknown only if every component is).

One of: "operational" , "degraded" , "outage" , "unknown"

StatusReport

object

Field	Type	Description
`status`required	`ComponentStatus`
`updatedAt`required	`string`	When the state was computed (RFC 3339 UTC).
`windowSeconds`required	`integer`	The window judged, in seconds.
`components`required	`array of object`
`components[].id`required	`string`	One of: "api", "generation", "image_provider", "vision_provider"
`components[].name`required	`string`
`components[].status`required	`ComponentStatus`	`unknown`: no recent traffic to judge from, or the state could not be read.

ApiKeyScope

string

Permission an API key carries. Access tokens implicitly hold every scope.

One of: "generations:write" , "generations:read" , "uploads:write" , "usage:read" , "keys:manage" , "billing:read" , "billing:write" , "webhooks:read" , "webhooks:write"

Me

object

Field	Type	Description
`user`required	`object`
`user.id`required	`string`	Format: uuid
`user.displayName`required	`string`nullable
`user.avatarUrl`required	`string`nullable
`user.email`	`string`	Only when authenticated with an access token.
`user.createdAt`required	`string`	RFC 3339 UTC timestamp.
`credential`required	`object`
`credential.type`required	`string`	One of: "user_token", "api_key"
`credential.environment`required	`ApiKeyEnvironment`
`credential.scopes`required	`array of ApiKeyScope`
`credential.apiKey`	`object`	Only when authenticated with an API key. Never the secret.
`credential.apiKey.id`required	`string`	Format: uuid
`credential.apiKey.name`required	`string`
`credential.apiKey.prefix`required	`string`
`credential.apiKey.expiresAt`required	`string`nullable	RFC 3339 UTC timestamp.

ApiKey

object

Field	Type	Description
`id`required	`string`	Format: uuid
`name`required	`string`
`prefix`required	`string`	First characters of the key, for display.
`environment`required	`ApiKeyEnvironment`
`scopes`required	`array of ApiKeyScope`
`status`required	`string`	One of: "active", "expired"
`createdAt`required	`string`	RFC 3339 UTC timestamp.
`lastUsedAt`required	`string`nullable	RFC 3339 UTC timestamp.
`expiresAt`required	`string`nullable	RFC 3339 UTC timestamp.

CreatedApiKey

ApiKey & object

Field	Type	Description
`id`required	`string`	Format: uuid
`name`required	`string`
`prefix`required	`string`	First characters of the key, for display.
`environment`required	`ApiKeyEnvironment`
`scopes`required	`array of ApiKeyScope`
`status`required	`string`	One of: "active", "expired"
`createdAt`required	`string`	RFC 3339 UTC timestamp.
`lastUsedAt`required	`string`nullable	RFC 3339 UTC timestamp.
`expiresAt`required	`string`nullable	RFC 3339 UTC timestamp.
`key`required	`string`	The full secret. Returned only in this response; store it now.

CreateApiKeyRequest

object

Field	Type	Description
`name`required	`string`	1–64 characters after trimming; need not be unique.
`environment`required	`ApiKeyEnvironment`
`scopes`	`array of ApiKeyScope`	Defaults to every scope except `keys:manage`, `billing:read`, `billing:write`, `webhooks:read` and `webhooks:write`.
`expiresAt`	`string`	Optional RFC 3339 expiry, in the future and at most 365 days ahead.Format: date-time

ApiKeyList

object

Non-revoked keys, newest first (at most 100).

Field	Type	Description
`data`required	`array of ApiKey`

DeviceAuthorization

object

Field	Type	Description
`device_code`required	`string`	Secret. Send it to `POST /auth/device/token`; never show it to anyone.
`user_code`required	`string`	Show it to the human: they confirm it in the console.
`verification_uri`required	`string`	Format: uri
`verification_uri_complete`required	`string`	The verification page with the code filled in.Format: uri
`expires_in`required	`integer`	Seconds until the codes expire.
`interval`required	`integer`	Seconds to wait between polls of `POST /auth/device/token`.

DeviceAuthorizationRequest

object

Field	Type	Description
`client_name`	`string`	Your tool’s name, shown to the human as an unverified label. 1–64 printable ASCII characters. When absent, `client_id` is used instead (generic OAuth libraries send one).
`scope`	`string`	Space-separated scopes for the new key. Default `generations:write generations:read uploads:write usage:read`. `keys:manage`, `billing:write` and `webhooks:write` cannot be requested. The human may narrow the list, or add `billing:read` and `webhooks:read`.
`environment`	`ApiKeyEnvironment`	Environment of the new key. Default `live`.

DeviceToken

object

Field	Type	Description
`access_token`required	`string`	The new API key (`ss_live_…` or `ss_test_…`). Returned once: store it now.
`token_type`required	`string`	One of: "Bearer"
`scope`required	`string`	Space-separated scopes the human approved (may be narrower than requested).
`key_id`required	`string`	Id of the new API key.Format: uuid
`environment`required	`ApiKeyEnvironment`

DeviceTokenError

object

OAuth 2.0 error body (RFC 6749 §5.2, RFC 8628 §3.5): the one deliberate exception to ErrorEnvelope. X-Request-Id is still in the response headers.

Field	Type	Description
`error`required	`string`	One of: "authorization_pending", "slow_down", "access_denied", "expired_token", "invalid_grant", "invalid_request", "unsupported_grant_type"
`error_description`required	`string`

DeviceTokenRequest

object

Field	Type	Description
`grant_type`required	`string`	One of: "urn:ietf:params:oauth:grant-type:device_code"
`device_code`required	`string`

CreditBalances

object

Remaining credits. A caller with no credits reads all zeros.

Field	Type	Description
`balances`required	`object`
`balances.starter`required	`integer`
`balances.subscription`required	`integer`
`balances.purchased`required	`integer`
`total`required	`integer`	Sum of the three balances.

UsageGroupBy

string

day: one bucket per UTC day in the range, including empty days. key: per API key id (none for calls without a key). source: per surface (mobile, api, web, mcp, cli).

One of: "day" , "key" , "source"

UsageCounts

object

Field	Type	Description
`generations`required	`integer`	Generations started in the bucket.
`succeeded`required	`integer`	Completed.
`failed`required	`integer`	Failed before any credit was charged.
`refunded`required	`integer`	Charged, then refunded.
`pending`required	`integer`	Still running.
`creditsUsed`required	`integer`	Credits charged minus credits refunded for these generations. One generation can use several credits.

UsageBucket

UsageCounts & object

Field	Type	Description
`generations`required	`integer`	Generations started in the bucket.
`succeeded`required	`integer`	Completed.
`failed`required	`integer`	Failed before any credit was charged.
`refunded`required	`integer`	Charged, then refunded.
`pending`required	`integer`	Still running.
`creditsUsed`required	`integer`	Credits charged minus credits refunded for these generations. One generation can use several credits.
`key`required	`string`	The UTC day, API key id or source.

UsageReport

object

Live usage of the whole account (every key and surface; test keys are unbilled and not counted), bucketed by when each generation started. Refunds always count against the generation they belong to.

Field	Type	Description
`from`required	`string`	Resolved start (inclusive).
`to`required	`string`	Resolved end (exclusive).
`groupBy`required	`UsageGroupBy`
`data`required	`array of UsageBucket`	Buckets sorted by `key`.
`totals`required	`UsageCounts`

UploadStatus

string

pending: presigned, waiting for the file and complete. ready: usable in generations. failed: the file was rejected (it is deleted). deleted: deleted by you or by retention (metadata only).

One of: "pending" , "ready" , "failed" , "deleted"

UploadOrientation

string

From the EXIF-oriented size; square when equal.

One of: "portrait" , "landscape" , "square"

Upload

object

Field	Type	Description
`id`required	`string`	Format: uuid
`status`required	`UploadStatus`
`source`required	`string`	How the file arrived: a multipart upload, a presigned PUT, or a URL import.One of: "multipart", "presign", "url"
`environment`required	`ApiKeyEnvironment`
`contentType`required	`string`	Detected from the file bytes (for a pending presigned upload: the declared type).One of: "image/png", "image/jpeg", "image/webp"
`bytes`required	`integer`	File size (declared, while pending).
`width`required	`integer`nullable	Pixels, EXIF-oriented. Null unless ready.
`height`required	`integer`nullable	Pixels, EXIF-oriented. Null unless ready.
`orientation`required	`UploadOrientation`
`sha256`required	`string`nullable	Hex SHA-256 of the file. Null unless ready.
`sourceUrl`required	`string`nullable	URL imports only: origin and path of the URL you sent (query and fragment are never stored).
`expiresAt`required	`string`	When the upload and its file are deleted: 30 days after creation (24 hours for pending or failed uploads). Generated results are kept until you delete them.
`createdAt`required	`string`	RFC 3339 UTC timestamp.

CreateUploadFromUrl

object

Field	Type	Description
`url`required	`string`	An `https://` URL (port 443, no credentials, at most 2048 characters) that resolves to a public address. Fetched once, server-side.

PresignedUpload

object

Field	Type	Description
`upload`required	`Upload`
`uploadUrl`required	`string`	PUT the file here, from your server.Format: uri
`method`required	`string`	One of: "PUT"
`headers`required	`object`	Send exactly these headers with the PUT (they are signed).
`uploadUrlExpiresAt`required	`string`	15 minutes after this response.

PresignUploadRequest

object

Field	Type	Description
`contentType`required	`string`	The type of the file you will PUT: `image/png`, `image/jpeg` or `image/webp`.
`bytes`required	`integer`	Exact size of the file you will PUT, at most 20 MB (20971520).

UploadList

object

Uploads that are not deleted, newest first.

Field	Type	Description
`data`required	`array of Upload`
`nextCursor`required	`string`nullable	Pass as `cursor` for the next page; null on the last page.

GenerationResult

object

Only when succeeded and not deleted.

Field	Type	Description
`image`required	`object`
`image.url`required	`string`	Signed download URL (expires at `urlsExpireAt`).Format: uri
`image.contentType`required	`string`	PNG; JPEG for the Google Play feature graphic.One of: "image/png", "image/jpeg"
`image.width`required	`integer`
`image.height`required	`integer`
`thumbnail`required	`object`nullable	A 512 px preview. Best effort: its URL may return 404.
`thumbnail.url`required	`string`	Format: uri
`thumbnail.contentType`required	`string`	One of: "image/webp"
`urlsExpireAt`required	`string`	15 minutes after this response. Fetch the generation again for fresh URLs.
`caption`required	`string`	The caption used: yours, or the one derived from the screenshot (may be empty).
`palette`required	`array of PaletteColor`	The colours used.

GenerationSource

string

Since 1.15.0 (always sent): where the request that created it came from.

One of: "mobile" , "api" , "web" , "mcp" , "cli"

ProjectRef

object

Since 1.15.0 (always sent): its project, directly or through its screenshot set (POST /projects/{id}/items).

Field	Type	Description
`id`required	`string`	Format: uuid
`name`required	`string`

StyleField

string

A field a style can supply to a generation or screenshot set.

One of: "palette" , "logo" , "backgroundMood" , "backgroundPrompt" , "captionTone"

StyleRef

object

Since 1.18.0 (always sent): the style (styleId) it was made with, for an image of a screenshot set its set’s; null when none.

Field	Type	Description
`id`required	`string`nullable	`null` once the style was deleted (the generation keeps what it used).Format: uuid
`name`required	`string`
`applied`required	`array of StyleField`	What the style supplied, as it was at creation. Fields you sent yourself are not listed.

Generation

object

Field	Type	Description
`id`required	`string`	Format: uuid
`status`required	`GenerationStatus`
`environment`required	`ApiKeyEnvironment`
`inputs`required	`array of object`
`inputs[].uploadId`required	`string`	Format: uuid
`inputs[].sourceUrl`required	`string`nullable	For a URL input: origin and path of the URL (it was imported as `uploadId`).
`store`required	`StoreTarget`
`device`required	`string`	Catalogue id of the size.
`size`required	`object`
`size.width`required	`integer`
`size.height`required	`integer`
`orientation`required	`Orientation`
`app`required	`object`
`app.name`required	`string`
`app.description`required	`string`
`caption`required	`string`nullable	As requested; null = derive.
`palette`required	`array of PaletteColor`nullable	As requested, or from the style (`style.applied` contains `palette`); null = extract from the screenshot.
`logo`required	`object`nullable
`logo.uploadId`required	`string`	Format: uuid
`metadata`required	`object`
`creditsCharged`required	`integer`	1 for live keys, 0 for test keys.
`creditsRefunded`required	`integer`	Refunded when the generation failed or was canceled before it started.
`result`required	`GenerationResult`
`error`required	`object`nullable	Only when `failed`. See /v1/docs/errors for each code.
`error.code`required	`string`	One of: "GENERATION_FAILED", "GENERATION_TIMEOUT", "NOT_A_SCREENSHOT", "UPLOAD_NOT_READY", "INTERNAL_ERROR"
`error.message`required	`string`
`createdAt`required	`string`	RFC 3339 UTC timestamp.
`startedAt`required	`string`nullable	RFC 3339 UTC timestamp.
`finishedAt`required	`string`nullable	RFC 3339 UTC timestamp.
`deletedAt`required	`string`nullable	Set by `DELETE`: the result files are gone, this record stays.
`screenshotSet`	`object`	Present only when this generation is an image of a screenshot set (`POST /screenshot-sets`).
`screenshotSet.id`required	`string`	Format: uuid
`screenshotSet.position`required	`integer`	The screen (1-based).
`screenshotSet.attempt`required	`integer`	2 and up: a retry.
`source`	`GenerationSource`
`clientName`	`string`nullable	Since 1.15.0 (always sent): the `X-Storeshot-Client` header of the request (e.g. `cli/storeshot@1.2.0`), else its sanitised `User-Agent`. Self-asserted: for your records only.
`requestId`	`string`nullable	Since 1.15.0 (always sent): the `X-Request-Id` of the request that created it (quote it to support). Null for test generations made before 1.15.0.
`project`	`ProjectRef`
`style`	`StyleRef`

GenerationInput

object

An image: an upload id or an https URL.

GenerationSize

object

Output pixels: a catalogue size of the store (portrait, or swapped for landscape; the Google Play feature graphic is 1024×500 only).

Field	Type	Description
`width`required	`integer`
`height`required	`integer`

GenerationMetadata

object

Your own labels, echoed back and filterable (GET /generations?metadata=key:value): at most 20 keys of 1–40 characters (A-Z a-z 0-9 _ . -), string values of at most 500 characters, 4 KB in total.

CreateGenerationRequest

object

Field	Type	Description
`inputs`required	`array of GenerationInput`	Exactly one screenshot in this version.
`store`required	`StoreTarget`
`device`	`string`	A `GET /devices` id of the same store. Exactly one of `device` and `size` is required.
`size`	`GenerationSize`
`orientation`	`Orientation`	Default: from `size` (wider than tall is landscape), else portrait (the feature graphic: landscape). Must agree with the size and the device.
`app`required	`object`
`app.name`required	`string`
`app.description`	`string`	Default: ""
`caption`	`string`	The marketing caption. Absent or blank: derived from the screenshot.
`palette`	`array of PaletteColor`	1–8 colours. Absent: extracted from the screenshot.
`logo`	`GenerationInput`	Your app icon or logo (any shape; PNG, JPEG or WebP).
`metadata`	`GenerationMetadata`
`projectId`	`string`	Since 1.15.0: put the generation in this project of yours (`GET /projects`). The project does not change how it is generated.Format: uuid
`styleId`	`string`	Since 1.18.0: a style of yours (`GET /styles`). It fills `palette` and `logo` when you leave them out and adds its background mood, description and caption tone. It is copied into the generation: editing or deleting the style later changes nothing here.Format: uuid

GenerationList

object

Generations that are not deleted, newest first.

Field	Type	Description
`data`required	`array of Generation`
`nextCursor`required	`string`nullable	Pass as `cursor` for the next page; null on the last page.

ScreenshotSetQuote

object

Nothing was created or charged. A quote is not a reservation.

Field	Type	Description
`dryRun`required	`boolean`	One of: true
`environment`required	`ApiKeyEnvironment`
`images`required	`integer`
`credits`required	`integer`	What creating this set charges now (1 per image with a live key, 0 with a test key).
`availableCredits`required	`integer`
`sufficient`required	`boolean`
`screens`required	`integer`
`breakdown`required	`array of object`
`breakdown[].store`required	`StoreTarget`
`breakdown[].device`required	`string`
`breakdown[].size`required	`object`
`breakdown[].size.width`required	`integer`
`breakdown[].size.height`required	`integer`
`breakdown[].orientation`required	`Orientation`
`breakdown[].images`required	`integer`
`breakdown[].defaulted`required	`boolean`	The store default (no `devices` given).

ScreenshotSet

object

Field	Type	Description
`id`required	`string`	Format: uuid
`status`required	`ScreenshotSetStatus`
`environment`required	`ApiKeyEnvironment`
`app`required	`object`
`app.name`required	`string`
`app.description`required	`string`
`orientation`required	`Orientation`
`palette`required	`array of PaletteColor`	The palette of every image: as requested, or from the style (`style.applied` contains `palette`), or extracted.
`paletteSource`required	`string`	`auto`: extracted from screen 1 when the set was created.One of: "given", "auto"
`logo`required	`object`nullable
`logo.uploadId`required	`string`	Format: uuid
`metadata`required	`object`
`screens`required	`array of object`
`screens[].position`required	`integer`
`screens[].input`required	`object`
`screens[].input.uploadId`required	`string`	Format: uuid
`screens[].caption`required	`string`
`stores`required	`array of object`
`stores[].store`required	`StoreTarget`
`stores[].devices`required	`array of string`
`stores[].featureGraphic`required	`object`nullable
`stores[].featureGraphic.screen`required	`integer`
`stores[].featureGraphic.caption`required	`string`
`images`required	`integer`
`counts`required	`object`
`counts.queued`required	`integer`
`counts.running`required	`integer`
`counts.succeeded`required	`integer`
`counts.failed`required	`integer`
`counts.canceled`required	`integer`
`creditsCharged`required	`integer`	Every image of the set, retries included (0 with a test key).
`creditsRefunded`required	`integer`
`children`required	`array of object`	The current image of every slot (store, device, screen). Result URLs: `GET /generations?screenshotSetId=` or the archive.
`children[].position`required	`integer`	The screen (1-based).
`children[].store`required	`StoreTarget`
`children[].device`required	`string`
`children[].size`required	`object`
`children[].size.width`required	`integer`
`children[].size.height`required	`integer`
`children[].featureGraphic`required	`boolean`
`children[].generationId`required	`string`	Format: uuid
`children[].attempt`required	`integer`
`children[].status`required	`GenerationStatus`
`children[].error`required	`object`nullable
`children[].error.code`required	`string`	One of: "GENERATION_FAILED", "GENERATION_TIMEOUT", "NOT_A_SCREENSHOT", "UPLOAD_NOT_READY", "INTERNAL_ERROR"
`children[].error.message`required	`string`
`archiveUrl`required	`string`
`createdAt`required	`string`	RFC 3339 UTC timestamp.
`updatedAt`required	`string`	RFC 3339 UTC timestamp.
`finishedAt`required	`string`nullable	RFC 3339 UTC timestamp.
`deletedAt`required	`string`nullable	RFC 3339 UTC timestamp.
`preview`	`ScreenshotSetPreview`
`source`	`GenerationSource`	Since 1.15.0 (always sent; absent from `screenshot_set.completed` events): the source of the request that created the set.
`project`	`ProjectRef`	Since 1.15.0 (always sent; absent from `screenshot_set.completed` events): its project (`POST /projects/{id}/items`).
`style`	`StyleRef`	Since 1.18.0 (always sent; absent from `screenshot_set.completed` events): the style (`styleId`) it was made with; `null` when none.

SetUploadRef

object

An upload id (URL inputs are not accepted in sets).

Field	Type	Description
`uploadId`required	`string`	A `ready` upload of the same environment (test or live) as the credential.Format: uuid

ScreenshotSetScreen

object

Field	Type	Description
`input`required	`SetUploadRef`
`caption`required	`string`	Required (1–1000 characters): the same caption is used on every device of this screen.

ScreenshotSetFeatureGraphic

boolean or object

Google Play only. true: one 1024×500 feature graphic from screen 1 with its caption (+1 image).

ScreenshotSetTarget

object

Field	Type	Description
`store`required	`StoreTarget`
`devices`	`array of string`	`GET /devices` screenshot ids of this store that meet its rules (`GET /stores/{store}/requirements`). Absent: the store defaults (App Store: `app_store_1290x2796` and `app_store_1179x2556`, the 6.9” and 6.3” iPhone groups Apple asks for; Google Play: `google_play_1080x1920`). At most one size per device class (for a taller Play phone, `google_play_1080x2160` instead of `google_play_1080x1920`). Pass fewer devices to pay for fewer images.
`featureGraphic`	`ScreenshotSetFeatureGraphic`

CreateScreenshotSetRequest

object

Field	Type	Description
`app`required	`object`
`app.name`required	`string`
`app.description`	`string`	Default: ""
`screens`required	`array of ScreenshotSetScreen`	1–10 screenshots, in listing order.
`stores`required	`array of ScreenshotSetTarget`
`orientation`	`Orientation`	Of the screenshots (the feature graphic is always landscape).Default: "portrait"
`palette`	`array of PaletteColor`	1–8 colours. Absent: extracted once from screen 1 and used for every image.
`logo`	`SetUploadRef`	Your app icon or logo, used on every image.
`metadata`	`GenerationMetadata`
`projectId`	`string`	Since 1.15.0: put the set (and so every image of it, retries included) in this project of yours.Format: uuid
`styleId`	`string`	Since 1.18.0: a style of yours (`GET /styles`). It fills `palette` and `logo` when you leave them out and adds its background mood, description and caption tone to every image. It is copied into the set and its retries: editing or deleting the style later changes nothing here. With `?dryRun=true` the style is checked; styles are free, so the quote is the same.Format: uuid

ScreenshotSetList

object

Sets that are not deleted, newest first.

Field	Type	Description
`data`required	`array of ScreenshotSet`
`nextCursor`required	`string`nullable

ScreenshotSetRetryResult

object

Field	Type	Description
`created`required	`array of object`
`created[].generationId`required	`string`	Format: uuid
`created[].position`required	`integer`
`created[].device`required	`string`
`created[].attempt`required	`integer`
`skipped`required	`array of object`
`skipped[].generationId`required	`string`	Format: uuid
`skipped[].reason`required	`string`	One of: "superseded", "not_failed", "attempts_exhausted"

RetriedScreenshotSet

ScreenshotSet & object

Field	Type	Description
`id`required	`string`	Format: uuid
`status`required	`ScreenshotSetStatus`
`environment`required	`ApiKeyEnvironment`
`app`required	`object`
`app.name`required	`string`
`app.description`required	`string`
`orientation`required	`Orientation`
`palette`required	`array of PaletteColor`	The palette of every image: as requested, or from the style (`style.applied` contains `palette`), or extracted.
`paletteSource`required	`string`	`auto`: extracted from screen 1 when the set was created.One of: "given", "auto"
`logo`required	`object`nullable
`logo.uploadId`required	`string`	Format: uuid
`metadata`required	`object`
`screens`required	`array of object`
`screens[].position`required	`integer`
`screens[].input`required	`object`
`screens[].input.uploadId`required	`string`	Format: uuid
`screens[].caption`required	`string`
`stores`required	`array of object`
`stores[].store`required	`StoreTarget`
`stores[].devices`required	`array of string`
`stores[].featureGraphic`required	`object`nullable
`stores[].featureGraphic.screen`required	`integer`
`stores[].featureGraphic.caption`required	`string`
`images`required	`integer`
`counts`required	`object`
`counts.queued`required	`integer`
`counts.running`required	`integer`
`counts.succeeded`required	`integer`
`counts.failed`required	`integer`
`counts.canceled`required	`integer`
`creditsCharged`required	`integer`	Every image of the set, retries included (0 with a test key).
`creditsRefunded`required	`integer`
`children`required	`array of object`	The current image of every slot (store, device, screen). Result URLs: `GET /generations?screenshotSetId=` or the archive.
`children[].position`required	`integer`	The screen (1-based).
`children[].store`required	`StoreTarget`
`children[].device`required	`string`
`children[].size`required	`object`
`children[].size.width`required	`integer`
`children[].size.height`required	`integer`
`children[].featureGraphic`required	`boolean`
`children[].generationId`required	`string`	Format: uuid
`children[].attempt`required	`integer`
`children[].status`required	`GenerationStatus`
`children[].error`required	`object`nullable
`children[].error.code`required	`string`	One of: "GENERATION_FAILED", "GENERATION_TIMEOUT", "NOT_A_SCREENSHOT", "UPLOAD_NOT_READY", "INTERNAL_ERROR"
`children[].error.message`required	`string`
`archiveUrl`required	`string`
`createdAt`required	`string`	RFC 3339 UTC timestamp.
`updatedAt`required	`string`	RFC 3339 UTC timestamp.
`finishedAt`required	`string`nullable	RFC 3339 UTC timestamp.
`deletedAt`required	`string`nullable	RFC 3339 UTC timestamp.
`preview`	`ScreenshotSetPreview`
`source`	`GenerationSource`	Since 1.15.0 (always sent; absent from `screenshot_set.completed` events): the source of the request that created the set.
`project`	`ProjectRef`	Since 1.15.0 (always sent; absent from `screenshot_set.completed` events): its project (`POST /projects/{id}/items`).
`style`	`StyleRef`	Since 1.18.0 (always sent; absent from `screenshot_set.completed` events): the style (`styleId`) it was made with; `null` when none.
`retry`required	`ScreenshotSetRetryResult`

RetryScreenshotSetRequest

object

Field	Type	Description
`generationIds`	`array of string`	Images of this set to retry. Absent: every failed or canceled image.

Project

object

Groups generations and screenshot sets of one app. Its palette and logo are stored for you; generations do not inherit them (send them in each request).

Field	Type	Description
`id`required	`string`	Format: uuid
`name`required	`string`
`description`required	`string`
`store`required	`StoreTarget`
`palette`required	`array of PaletteColor`
`logo`required	`object`nullable
`logo.url`required	`string`	Signed URL (expires at `expiresAt`).Format: uri
`logo.expiresAt`required	`string`	RFC 3339 UTC timestamp.
`counts`required	`object`
`counts.generations`required	`integer`	Standalone generations in the project (the images of a set count in it).
`counts.screenshotSets`required	`integer`
`preview`required	`ScreenshotSetPreview`	The most recently finished succeeded image (with a thumbnail) of its generations and sets; `null` while there is none.
`createdAt`required	`string`	RFC 3339 UTC timestamp.
`updatedAt`required	`string`	RFC 3339 UTC timestamp.

CreateProjectRequest

object

Field	Type	Description
`name`required	`string`
`description`	`string`
`store`	`StoreTarget`	Default `google_play`.
`palette`	`array of PaletteColor`
`logo`	`object`
`logo.uploadId`required	`string`	A `ready` upload of this account (PNG, JPEG or WebP; either environment). It is copied: deleting the upload later keeps the logo.Format: uuid

ProjectList

object

Projects, most recently updated first.

Field	Type	Description
`data`required	`array of Project`
`nextCursor`required	`string`nullable	Pass as `cursor` for the next page; null on the last page.

UpdateProjectRequest

object

Field	Type	Description
`name`	`string`
`description`	`string`
`store`	`StoreTarget`
`palette`	`array of PaletteColor`	Replaces the palette; `[]` clears it.
`logo`	`object`nullable	A new logo, or `null` to remove it.
`logo.uploadId`required	`string`	A `ready` upload of this account (PNG, JPEG or WebP; either environment). It is copied: deleting the upload later keeps the logo.Format: uuid

ProjectItemsAdded

object

Field	Type	Description
`projectId`required	`string`	Format: uuid
`added`required	`integer`	Items newly in this project (moved from another project or from none).

ProjectItemsRequest

object

1–100 ids in total. An API key can only use items of its own environment; an access token any.

Field	Type	Description
`generationIds`	`array of string`	Ids of your standalone generations (an image of a set moves with its set).
`screenshotSetIds`	`array of string`	Ids of your screenshot sets.

ProjectItemsRemoved

object

Field	Type	Description
`projectId`required	`string`	Format: uuid
`removed`required	`integer`	Items that left this project (items in another project are left alone).

BackgroundMood

string

The look of the background: minimal, light, dark, vibrant, gradient or textured.

One of: "minimal" , "light" , "dark" , "vibrant" , "gradient" , "textured"

CaptionTone

string

The voice of the headline: professional, friendly, playful, bold or premium. A caption you send is kept word for word; the tone guides its typography and any wording the model writes.

One of: "professional" , "friendly" , "playful" , "bold" , "premium"

Style

object

A brand kit: send its id as styleId when you create a generation or a screenshot set. It fills the palette and logo you leave out and adds its background mood, description and caption tone; fields you send win. Generations and sets keep a copy of what they used, so editing or deleting the style never changes them or their retries.

Field	Type	Description
`id`required	`string`	Format: uuid
`name`required	`string`
`palette`required	`array of PaletteColor`
`logo`required	`object`nullable
`logo.url`required	`string`	Signed URL (expires at `expiresAt`).Format: uri
`logo.expiresAt`required	`string`	RFC 3339 UTC timestamp.
`backgroundMood`required	`BackgroundMood`
`backgroundPrompt`required	`string`nullable
`captionTone`required	`CaptionTone`
`referenceGenerationId`required	`string`nullable	The generation the values were copied from, if any (provenance only).Format: uuid
`createdAt`required	`string`	RFC 3339 UTC timestamp.
`updatedAt`required	`string`	RFC 3339 UTC timestamp.

CreateStyleRequest

object

Field	Type	Description
`name`required	`string`
`palette`	`array of PaletteColor`	1–8 colours.
`logo`	`object`
`logo.uploadId`required	`string`	A `ready` upload of this account (PNG, JPEG or WebP, at most 5 MB and 4096 × 4096 pixels; either environment). It is copied: deleting the upload later keeps the logo.Format: uuid
`backgroundMood`	`BackgroundMood & string`
`backgroundPrompt`	`string`	At most 200 characters on one line: what the background looks like. It is passed to the model as a quoted description of the look, never as instructions.
`captionTone`	`CaptionTone & string`
`referenceGenerationId`	`string`	A succeeded generation of yours: its colours (and, when it was made with a style, that style’s background and caption choices) are copied into the fields you leave out, once. Its image and logo are not used.Format: uuid

StyleList

object

Styles, most recently updated first.

Field	Type	Description
`data`required	`array of Style`
`nextCursor`required	`string`nullable	Pass as `cursor` for the next page; null on the last page.

UpdateStyleRequest

object

Field	Type	Description
`name`	`string`
`palette`	`array of PaletteColor`	Replaces the palette; `[]` clears it.
`logo`	`object`nullable	A new logo, or `null` to remove it.
`logo.uploadId`required	`string`	A `ready` upload of this account (PNG, JPEG or WebP, at most 5 MB and 4096 × 4096 pixels; either environment). It is copied: deleting the upload later keeps the logo.Format: uuid
`backgroundMood`	`BackgroundMood`	`null` clears it.
`backgroundPrompt`	`string`nullable	At most 200 characters on one line; `null` clears it.
`captionTone`	`CaptionTone`	`null` clears it.
`referenceGenerationId`	`string`nullable	Copy from this generation again (into the fields you leave out), or `null` to forget where the values came from (the values stay).Format: uuid

ExtractedColor

object

Field	Type	Description
`hex`required	`string`	Uppercase `#RRGGBB`.
`name`required	`string`	Nearest named colour.
`inputIndex`	`integer`	`dominant` only: index in `inputs` of the image this colour came from.

Palette

object

Field	Type	Description
`mode`required	`string`	One of: "extract", "dominant"
`source`required	`string`	`default`: no colour could be extracted, so `colors` is the Storeshot default palette.One of: "extracted", "default"
`colors`required	`array of ExtractedColor`

PaletteInput

object

An image: an upload id or an https URL.

CreatePaletteRequest

object

Field	Type	Description
`inputs`required	`array of PaletteInput`	`extract`: exactly one image. `dominant`: 1–10 images. At most 3 URL inputs.
`mode`	`string`	`extract`: up to `maxColors` distinct colours of one image (the Storeshot app’s palette). `dominant`: the dominant colour of each image.One of: "extract", "dominant"Default: "extract"
`maxColors`	`integer`	`extract` only: 1–10, default 5.

StoreSummary

object

Field	Type	Description
`id`required	`StoreTarget`
`name`required	`string`
`requirementsUrl`required	`string`

StoreList

object

Field	Type	Description
`data`required	`array of StoreSummary`

StoreRuleIssue

string

One of: "size_not_accepted" , "edge_below_min" , "edge_above_max" , "aspect_ratio_exceeds_2_1" , "aspect_ratio_not_exact"

StoreDeviceClass

object

Field	Type	Description
`id`required	`string`
`family`required	`string`	One of: "iphone", "ipad", "watch", "phone", "tablet", "chromebook", "xr"
`label`required	`string`
`requirement`required	`string`	`conditional`: named by a `requiredGroups` entry (one of its classes is needed when its condition holds); `optional`: never needed.One of: "required", "conditional", "optional"
`count`required	`object`	Screenshots per locale when this class is provided.
`count.min`required	`integer`
`count.max`required	`integer`
`maxFileBytes`required	`integer`nullable	Per-class file limit; null when the store publishes none.
`acceptedSizes`required	`array of object`nullable	App Store: every accepted pixel size (both orientations). Null when `rules` apply.
`acceptedSizes[].width`required	`integer`
`acceptedSizes[].height`required	`integer`
`rules`required	`object`nullable	Google Play: dimension rules. Null when `acceptedSizes` apply.
`rules.minEdge`required	`integer`	Shorter side, at least.
`rules.maxEdge`required	`integer`nullable	Longer side, at most (null: no published maximum).
`rules.maxAspectRatio`required	`number`	Longer side ÷ shorter side, at most.
`rules.exactAspectRatio`required	`string`nullable	`long:short` the image must match exactly, or null.
`rules.recommendedAspectRatios`required	`array of string`	Advisory (store promotion), not enforced.
`sources`required	`array of string`
`devices`required	`array of object`	`GET /devices` sizes of this class. `compliant: false` lists the hard store rules the size breaks (in portrait or landscape). A deprecated size (`deprecated: true`) names its `replacedBy`.
`devices[].id`required	`string`
`devices[].compliant`required	`boolean`
`devices[].issues`required	`array of StoreRuleIssue`
`devices[].deprecated`	`boolean`	`true`: still accepted (same output size) so existing requests keep working, but it breaks a store rule or is superseded. Never a default. Use `replacedBy`. Absent otherwise.
`devices[].replacedBy`	`string`	Deprecated devices only: the `GET /devices` id to use instead.

StoreRequirements

object

What a store needs from screenshots, from the official pages in sources (checked on checkedOn). Stores change their rules; treat this as guidance.

Field	Type	Description
`store`required	`StoreTarget`
`name`required	`string`
`screenshots`required	`object`
`screenshots.formats`required	`array of string`
`screenshots.alpha`required	`boolean`	false: no transparency (no alpha channel).
`screenshots.maxFileBytes`required	`integer`nullable	Null when the store publishes no limit (see a class’s own `maxFileBytes`).
`screenshots.count`required	`object`
`screenshots.count.minTotal`required	`integer`	Across all classes.
`screenshots.count.maxPerDeviceClass`required	`integer`
`screenshots.sources`required	`array of string`
`deviceClasses`required	`array of StoreDeviceClass`
`requiredGroups`required	`array of object`
`requiredGroups[].when`required	`string`
`requiredGroups[].anyOf`required	`array of string`	Provide at least one of these classes.
`requiredGroups[].sources`required	`array of string`
`featureGraphic`required	`object`nullable	Google Play only.
`featureGraphic.width`required	`integer`
`featureGraphic.height`required	`integer`
`featureGraphic.formats`required	`array of string`
`featureGraphic.alpha`required	`boolean`
`featureGraphic.maxFileBytes`required	`integer`nullable
`featureGraphic.required`required	`boolean`
`featureGraphic.sources`required	`array of string`
`featureGraphic.device`required	`string`
`sources`required	`array of object`
`sources[].id`required	`string`	One of: "apple_screenshot_specs", "play_preview_assets"
`sources[].title`required	`string`
`sources[].url`required	`string`	Format: uri
`sources[].checkedOn`required	`string`	Date the facts were last checked (UTC).

WebhookEventType

string

generation.succeeded; generation.failed (a generation ended failed or canceled: see data.status); screenshot_set.completed (a set reached a final status, again after a retry); credits.low (live only: the balance fell below creditsLowThreshold). webhook.test is sent on demand by POST /webhooks/{id}/test and needs no subscription.

One of: "generation.succeeded" , "generation.failed" , "screenshot_set.completed" , "credits.low"

Webhook

object

Field	Type	Description
`id`required	`string`	Format: uuid
`environment`required	`ApiKeyEnvironment`
`url`required	`string`	Masked: scheme, host and the last 4 characters of the path.
`events`required	`array of WebhookEventType`
`description`required	`string`
`enabled`required	`boolean`
`creditsLowThreshold`required	`integer`
`secret`required	`object`
`secret.hint`required	`string`	The last 4 characters.
`secret.rotatedAt`required	`string`nullable	RFC 3339 UTC timestamp.
`secret.previousExpiresAt`required	`string`nullable	Until then deliveries are also signed with the previous secret.
`createdAt`required	`string`	RFC 3339 UTC timestamp.
`updatedAt`required	`string`	RFC 3339 UTC timestamp.

WebhookWithSecret

Webhook & object

Field	Type	Description
`id`required	`string`	Format: uuid
`environment`required	`ApiKeyEnvironment`
`url`required	`string`	Masked: scheme, host and the last 4 characters of the path.
`events`required	`array of WebhookEventType`
`description`required	`string`
`enabled`required	`boolean`
`creditsLowThreshold`required	`integer`
`secret`required	`object`
`secret.hint`required	`string`	The last 4 characters.
`secret.rotatedAt`required	`string`nullable	RFC 3339 UTC timestamp.
`secret.previousExpiresAt`required	`string`nullable	Until then deliveries are also signed with the previous secret.
`createdAt`required	`string`	RFC 3339 UTC timestamp.
`updatedAt`required	`string`	RFC 3339 UTC timestamp.
`secret`required	`object`
`secret.hint`required	`string`	The last 4 characters.
`secret.rotatedAt`required	`string`nullable	RFC 3339 UTC timestamp.
`secret.previousExpiresAt`required	`string`nullable	Until then deliveries are also signed with the previous secret.
`secret.value`required	`string`	The signing secret (`whsec_…`). Returned only in this response; store it now. Verify `Storeshot-Signature` with it.

CreateWebhookRequest

object

Field	Type	Description
`url`required	`string`	An `https://` URL on port 443, without credentials, at most 2048 characters, whose host resolves only to public addresses (checked now and before every delivery). Shown masked afterwards.
`events`required	`array of WebhookEventType`	The business events to deliver (1–4, unique).
`description`	`string`	Free text, at most 200 characters.
`enabled`	`boolean`	Default `true`.
`creditsLowThreshold`	`integer`	Default 5.
`environment`	`ApiKeyEnvironment`	Which events the webhook receives: `live` or `test` (test-key generations and sets). Default: the API key environment (access tokens: `live`). An API key can only create webhooks of its own environment.

WebhookList

object

Webhooks, newest first (at most 10 per environment).

Field	Type	Description
`data`required	`array of Webhook`

UpdateWebhookRequest

object

Field	Type	Description
`url`	`string`	An `https://` URL on port 443, without credentials, at most 2048 characters, whose host resolves only to public addresses (checked now and before every delivery). Shown masked afterwards.
`events`	`array of WebhookEventType`	The business events to deliver (1–4, unique).
`description`	`string`	Free text, at most 200 characters.
`enabled`	`boolean`
`creditsLowThreshold`	`integer`	`credits.low` fires when the live balance falls below this many credits (1–10000).

RotateWebhookSecretRequest

object

Field	Type	Description
`gracePeriodSeconds`	`integer`	How long the previous secret keeps signing deliveries next to the new one (0–604800, default 86400). 0 drops it at once.

WebhookTestResult

object

Field	Type	Description
`eventId`required	`string`
`deliveryId`required	`string`	Format: uuid

WebhookDeliveryStatus

string

pending: queued or retrying. succeeded: a 2xx answer. exhausted: 8 attempts failed. failed: the destination was refused (blocked_destination, invalid_url) or the secret could not be read. canceled: the webhook was disabled before the attempt.

One of: "pending" , "succeeded" , "exhausted" , "failed" , "canceled"

WebhookDelivery

object

Field	Type	Description
`id`required	`string`	Format: uuid
`eventId`required	`string`
`eventType`required	`string`	One of: "generation.succeeded", "generation.failed", "screenshot_set.completed", "credits.low", "webhook.test"
`status`required	`WebhookDeliveryStatus`
`attempts`required	`integer`
`nextAttemptAt`required	`string`nullable	When `pending`: the next attempt is due then (null while one is in flight).
`createdAt`required	`string`	RFC 3339 UTC timestamp.
`finishedAt`required	`string`nullable	RFC 3339 UTC timestamp.
`log`required	`array of object`
`log[].attempt`required	`integer`
`log[].at`required	`string`	RFC 3339 UTC timestamp.
`log[].latencyMs`required	`integer`
`log[].statusCode`required	`integer`nullable
`log[].errorClass`required	`string`nullable	One of: "http_status", "timeout", "connect_failed", "tls_error", "dns_failure", "blocked_destination", "redirect", "invalid_url", "secret_unavailable"
`log[].responseSnippet`required	`string`nullable	First 256 characters of the response body, control characters removed.

WebhookDeliveryList

object

Deliveries of this webhook, newest first.

Field	Type	Description
`data`required	`array of WebhookDelivery`
`nextCursor`required	`string`nullable

ActivityEntry

object

Field	Type	Description
`id`required	`string`	Format: uuid
`type`required	`string`	`api_key.created`, `api_key.revoked`, `credits.granted`, `credits.removed`, `webhook.created`, `webhook.updated`, `webhook.deleted`, `webhook.secret_rotated`, `webhook.test_sent`, `console.signed_in`, `console.sessions_revoked`. New types may be added.
`createdAt`required	`string`	RFC 3339 UTC timestamp.
`actor`required	`object`
`actor.type`required	`string`	`user`: you (console or access token); `api_key`: one of your keys; `system`: Storeshot (payments, plan renewals).One of: "user", "api_key", "system"
`actor.apiKeyId`required	`string`nullable	Format: uuid
`actor.apiKeyPrefix`required	`string`nullable
`target`required	`object`nullable	What changed (`api_key`, `webhook`, `polar_order`, …).
`target.type`required	`string`
`target.id`required	`string`
`details`required	`object`	Type-specific, never secret: key name/prefix/environment, credits/bucket/reason, webhook host/events/changed fields, sign-in method.
`requestId`required	`string`nullable	The `X-Request-Id` of the request that made the change (null for Storeshot).

ActivityList

object

Account activity, newest first (kept 400 days).

Field	Type	Description
`data`required	`array of ActivityEntry`
`nextCursor`required	`string`nullable	Pass as `cursor` for the next page; null on the last page.

ActivityFamily

string

Only one family of types (api_key, credits, webhook, console).

One of: "api_key" , "credits" , "webhook" , "console"

BillingPack

object

Field	Type	Description
`id`required	`string`	Pack id to send as `pack`.
`name`required	`string`
`credits`required	`integer`	Purchased credits (never expire).
`priceAmount`required	`integer`	List price in minor units (cents). Taxes are applied at checkout.
`currency`required	`string`	ISO 4217, lowercase.

BillingPackList

object

Packs on sale, cheapest first. Empty while web payments are switched off.

Field	Type	Description
`data`required	`array of BillingPack`

BillingCheckout

object

Field	Type	Description
`id`required	`string`	Format: uuid
`status`required	`string`	`open` (send the buyer to `url`), `processing` (payment confirmed, credits on the way), `paid` (credits granted), `partially_refunded`, `refunded`, `expired` (not paid in time) or `failed`.One of: "open", "processing", "paid", "partially_refunded", "refunded", "expired", "failed"
`pack`required	`string`
`credits`required	`integer`
`priceAmount`required	`integer`	Minor units (cents).
`currency`required	`string`
`url`required	`string`nullable	Hosted checkout page (Polar). Null unless `status` is `open`.Format: uri
`expiresAt`required	`string`nullable	Format: date-time
`createdAt`required	`string`	Format: date-time
`paidAt`required	`string`nullable	Format: date-time
`creditsGranted`required	`integer`	Credits added to `purchased`.
`creditsReversed`required	`integer`	Credits taken back after a refund (spent credits are not taken twice).
`kind`	`string`	SS-012: present (`subscription`) only on plan checkouts; then `pack` and `plan` hold the plan id and the credits are the monthly allotment, added to `subscription`. Absent on pack checkouts.One of: "subscription"
`plan`	`string`	SS-012: the plan of a plan checkout (absent on pack checkouts).One of: "pro", "agency", "scale"
`planName`	`string`	SS-013: the plan name, on `GET /billing/checkouts/{id}` of a plan checkout only (absent on pack checkouts).
`subscriptionStatus`	`string`nullable	SS-013: the payment provider’s status of the subscription this plan checkout created (`active`, `trialing`, `past_due`, `canceled`, …), or null while none is linked yet. Only on `GET /billing/checkouts/{id}` of a plan checkout.

CreateBillingCheckoutRequest

object

Field	Type	Description
`pack`required	`string`
`successUrl`	`string`	Where the buyer lands after paying. Default: a static confirmation page. `https://` on storeshot.art, a storeshot.art subdomain or this API host; at most 2048 characters.Format: uri
`returnUrl`	`string`	Where “back” on the checkout page leads. Default: the credits page. `https://` on storeshot.art, a storeshot.art subdomain or this API host; at most 2048 characters.Format: uri

BillingPlanLimits

object

The limits that apply on a plan.

Field	Type	Description
`requestsPerMinutePerKey`required	`integer`
`requestsPerMinutePerUser`required	`integer`
`concurrentGenerations`required	`integer`
`dailyGenerations`required	`integer`	Credits per UTC day.
`maxStoredUploads`required	`integer`
`maxStoredUploadMegabytes`required	`integer`

BillingPlan

object

Field	Type	Description
`id`required	`string`	Plan id to send as `plan`.One of: "pro", "agency", "scale"
`name`required	`string`
`credits`required	`integer`	Credits added to `subscription` each paid month. They are used before any other credits and expire (reset) at renewal; pack credits never expire.
`priceAmount`required	`integer`	Monthly list price in minor units (cents). Taxes are applied at checkout.
`currency`required	`string`	ISO 4217, lowercase.
`interval`required	`string`	One of: "month"
`limits`required	`BillingPlanLimits`

BillingPlanList

object

Plans on sale, cheapest first. Empty while plans are switched off.

Field	Type	Description
`data`required	`array of BillingPlan`

BillingSubscription

object

The latest subscription of the account, or null.

Field	Type	Description
`id`required	`string`	Format: uuid
`plan`required	`string`nullable	Null when the subscription moved to a product that is not a Storeshot plan.One of: "pro", "agency", "scale"
`status`required	`string`	The payment provider status: `active`, `trialing`, `past_due`, `incomplete`, `incomplete_expired`, `unpaid`, `paused` or `canceled`.
`cancelAtPeriodEnd`required	`boolean`
`currentPeriodStart`required	`string`nullable	Format: date-time
`currentPeriodEnd`required	`string`nullable	Format: date-time
`pendingPlan`required	`string`nullable	A downgrade that takes effect at the next renewal.One of: "pro", "agency", "scale"
`creditsPerPeriod`required	`integer`
`subscriptionCredits`required	`integer`	The `subscription` balance now (expires at renewal).

BillingSubscriptionState

object

Field	Type	Description
`plan`required	`string`	The tier whose limits apply now. A plan applies while its subscription is active (until one day after the period end) or past due (three days after the period end).One of: "free", "pro", "agency", "scale"
`limits`required	`BillingPlanLimits`
`subscription`required	`BillingSubscription`

CreateSubscriptionCheckoutRequest

object

Field	Type	Description
`plan`required	`string`	One of: "pro", "agency", "scale"
`successUrl`	`string`	Where the buyer lands after paying. Default: a static confirmation page. `https://` on storeshot.art, a storeshot.art subdomain or this API host; at most 2048 characters.Format: uri
`returnUrl`	`string`	Where “back” on the checkout page leads. Default: the credits page. `https://` on storeshot.art, a storeshot.art subdomain or this API host; at most 2048 characters.Format: uri

ChangeSubscriptionRequest

object

Field	Type	Description
`plan`required	`string`	One of: "pro", "agency", "scale"

BillingPortalSession

object

Field	Type	Description
`url`required	`string`	Open it in the browser of the account owner.Format: uri
`expiresAt`required	`string`nullable	When a `session` link stops working; null for `email_login`.Format: date-time
`mode`required	`string`	`session`: signed in as this account. `email_login`: the provider asks for the billing email and sends a one-time code.One of: "session", "email_login"

CreatePortalSessionRequest

object

Field	Type	Description
`returnUrl`	`string`	Where “back” in the portal leads. Default: the credits page. `https://` on storeshot.art, a storeshot.art subdomain or this API host; at most 2048 characters.Format: uri