Uploads API reference - StoreShot docs

List uploads

GET /uploads

Auth: API key with scope uploads:write, generations:write or generations:read, or access token.

Requires uploads:write, generations:write or generations:read. Uploads of the account that are not deleted (every API key and environment), newest first.

Credits. Free: no credits.

Parameters

Name	In	Type	Description
`limit`	query	`integer`	1–100, default 20. Default: 20
`cursor`	query	`string`	`nextCursor` of the previous page.

Responses

200 A page of uploads.

Schema UploadList (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

Example 200 response

{
  "data": [
    {
      "id": "6f1c1f0e-8a5e-4b8e-9a51-0f0e1d2c3b4a",
      "status": "ready",
      "source": "multipart",
      "environment": "live",
      "contentType": "image/png",
      "bytes": 482113,
      "width": 1290,
      "height": 2796,
      "orientation": "portrait",
      "sha256": "9b1e5e5a3c0f8d2b7a6c4e1f0d9b8a7c6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b",
      "sourceUrl": null,
      "expiresAt": "2026-11-20T10:00:00.000Z",
      "createdAt": "2026-10-21T10:00:00.000Z"
    }
  ],
  "nextCursor": "string"
}

400 INVALID_INPUT. A credential sent in the query string is refused before authentication, without RateLimit headers.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

401 UNAUTHORIZED: missing, malformed, unknown, revoked or expired credential.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id

403 FORBIDDEN: see details.reason.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

429 RATE_LIMITED: the request rate of the API key (details.scope key) or of the account (user) is exhausted for this window, or too many failed authentication attempts came from this IP (no details.scope and no RateLimit headers). Retry after Retry-After seconds.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy , Retry-After

default Error (see ErrorEnvelope and /v1/docs/errors).

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

Upload an image

POST /uploads

Auth: API key with scope uploads:write, or access token.

Requires uploads:write. Send either multipart/form-data with one file part file, or JSON { "url": "https://…" } to have the server fetch the image (https only, public addresses only, at most 3 redirects and 15 seconds). PNG, JPEG or WebP, at most 20 MB and 50 megapixels; the format is detected from the bytes. HEIC is not supported. The upload is ready in the response. It is deleted 30 days after creation; generated results are kept until you delete them.

When to use. Once per raw screenshot (or logo) before creating generations or sets, which take upload ids. Use multipart for local files and { "url" } for public https images.

Credits. Free: no credits (counts towards the upload quota).

Request body `multipart/form-data`

Required.

Field	Type	Description
`file`required	`string`	Exactly one file part named `file`: PNG, JPEG or WebP, at most 20 MB and 50 megapixels.Format: binary

Request body `application/json`

Required. Schema CreateUploadFromUrl.

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.

Example request body

{
  "url": "https://example.com/screenshots/home.png"
}

Responses

201 Created and ready.

Schema Upload (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

Example 201 response

{
  "id": "6f1c1f0e-8a5e-4b8e-9a51-0f0e1d2c3b4a",
  "status": "ready",
  "source": "multipart",
  "environment": "live",
  "contentType": "image/png",
  "bytes": 482113,
  "width": 1290,
  "height": 2796,
  "orientation": "portrait",
  "sha256": "9b1e5e5a3c0f8d2b7a6c4e1f0d9b8a7c6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b",
  "sourceUrl": null,
  "expiresAt": "2026-11-20T10:00:00.000Z",
  "createdAt": "2026-10-21T10:00:00.000Z"
}

400 INVALID_INPUT. A credential sent in the query string is refused before authentication, without RateLimit headers.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

401 UNAUTHORIZED: missing, malformed, unknown, revoked or expired credential.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id

403 FORBIDDEN: see details.reason.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

413 PAYLOAD_TOO_LARGE (the request body is over its limit) or IMAGE_TOO_LARGE (see details.reason).

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

415 UNSUPPORTED_FORMAT: not a PNG, JPEG or WebP image (see details.reason).

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

422 URL_FETCH_FAILED: the URL could not be fetched (see details.reason).

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

429 RATE_LIMITED: the request rate of the API key (details.scope key) or of the account (user) is exhausted for this window, or too many failed authentication attempts came from this IP (no details.scope and no RateLimit headers). Retry after Retry-After seconds.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy , Retry-After

503 SERVICE_UNAVAILABLE: uploads are busy. Retry after Retry-After seconds.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy , Retry-After

default Error (see ErrorEnvelope and /v1/docs/errors).

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

Start a presigned upload

POST /uploads/presign

Auth: API key with scope uploads:write, or access token.

Requires uploads:write. Returns a pending upload and a URL to PUT the file to (from your server; valid 15 minutes), with the exact headers to send. Then call POST /uploads/{id}/complete. A pending upload that is never completed is deleted after 24 hours.

When to use. Only when your server should send the bytes straight to storage; agents and scripts use POST /uploads.

Credits. Free: no credits.

Request body `application/json`

Required. Schema PresignUploadRequest.

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).

Example request body

{
  "contentType": "image/png",
  "bytes": 482113
}

Responses

201 Pending upload and its presigned URL.

Schema PresignedUpload (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

Example 201 response

{
  "upload": {
    "id": "6f1c1f0e-8a5e-4b8e-9a51-0f0e1d2c3b4a",
    "status": "ready",
    "source": "multipart",
    "environment": "live",
    "contentType": "image/png",
    "bytes": 482113,
    "width": 1290,
    "height": 2796,
    "orientation": "portrait",
    "sha256": "9b1e5e5a3c0f8d2b7a6c4e1f0d9b8a7c6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b",
    "sourceUrl": null,
    "expiresAt": "2026-11-20T10:00:00.000Z",
    "createdAt": "2026-10-21T10:00:00.000Z"
  },
  "uploadUrl": "https://example.com",
  "method": "PUT",
  "headers": {
    "Content-Type": "image/png",
    "Content-Length": "482113"
  },
  "uploadUrlExpiresAt": "2026-10-21T12:00:00.000Z"
}

400 INVALID_INPUT. A credential sent in the query string is refused before authentication, without RateLimit headers.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

401 UNAUTHORIZED: missing, malformed, unknown, revoked or expired credential.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id

403 FORBIDDEN: see details.reason.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

413 PAYLOAD_TOO_LARGE (the request body is over its limit) or IMAGE_TOO_LARGE (see details.reason).

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

415 UNSUPPORTED_FORMAT: not a PNG, JPEG or WebP image (see details.reason).

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

429 RATE_LIMITED: the request rate of the API key (details.scope key) or of the account (user) is exhausted for this window, or too many failed authentication attempts came from this IP (no details.scope and no RateLimit headers). Retry after Retry-After seconds.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy , Retry-After

default Error (see ErrorEnvelope and /v1/docs/errors).

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

Complete a presigned upload

POST /uploads/{id}/complete

Auth: API key with scope uploads:write, or access token.

Requires uploads:write. Checks the file you PUT (size, format, caps) and makes the upload ready. Idempotent for a ready upload. 409 UPLOAD_NOT_READY with object_missing means the file has not arrived yet: PUT it, then retry. A rejected file makes the upload failed and is deleted.

Credits. Free: no credits.

Parameters

Name	In	Type	Description
`id` required	path	`string`	Upload id. An unknown or malformed id is 404.

Responses

200 Ready.

Schema Upload (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

Example 200 response

{
  "id": "6f1c1f0e-8a5e-4b8e-9a51-0f0e1d2c3b4a",
  "status": "ready",
  "source": "multipart",
  "environment": "live",
  "contentType": "image/png",
  "bytes": 482113,
  "width": 1290,
  "height": 2796,
  "orientation": "portrait",
  "sha256": "9b1e5e5a3c0f8d2b7a6c4e1f0d9b8a7c6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b",
  "sourceUrl": null,
  "expiresAt": "2026-11-20T10:00:00.000Z",
  "createdAt": "2026-10-21T10:00:00.000Z"
}

400 INVALID_INPUT. A credential sent in the query string is refused before authentication, without RateLimit headers.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

401 UNAUTHORIZED: missing, malformed, unknown, revoked or expired credential.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id

403 FORBIDDEN: see details.reason.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

404 NOT_FOUND: no such resource for this caller.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

409 UPLOAD_NOT_READY: see details.reason.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

413 PAYLOAD_TOO_LARGE (the request body is over its limit) or IMAGE_TOO_LARGE (see details.reason).

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

415 UNSUPPORTED_FORMAT: not a PNG, JPEG or WebP image (see details.reason).

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

429 RATE_LIMITED: the request rate of the API key (details.scope key) or of the account (user) is exhausted for this window, or too many failed authentication attempts came from this IP (no details.scope and no RateLimit headers). Retry after Retry-After seconds.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy , Retry-After

503 SERVICE_UNAVAILABLE: uploads are busy. Retry after Retry-After seconds.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy , Retry-After

default Error (see ErrorEnvelope and /v1/docs/errors).

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

Get an upload

GET /uploads/{id}

Auth: API key with scope uploads:write, generations:write or generations:read, or access token.

Requires uploads:write, generations:write or generations:read. Metadata only, in any status (deleted uploads included).

Credits. Free: no credits.

Parameters

Name	In	Type	Description
`id` required	path	`string`	Upload id. An unknown or malformed id is 404.

Responses

200 The upload.

Schema Upload (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

Example 200 response

{
  "id": "6f1c1f0e-8a5e-4b8e-9a51-0f0e1d2c3b4a",
  "status": "ready",
  "source": "multipart",
  "environment": "live",
  "contentType": "image/png",
  "bytes": 482113,
  "width": 1290,
  "height": 2796,
  "orientation": "portrait",
  "sha256": "9b1e5e5a3c0f8d2b7a6c4e1f0d9b8a7c6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b",
  "sourceUrl": null,
  "expiresAt": "2026-11-20T10:00:00.000Z",
  "createdAt": "2026-10-21T10:00:00.000Z"
}

400 INVALID_INPUT. A credential sent in the query string is refused before authentication, without RateLimit headers.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

401 UNAUTHORIZED: missing, malformed, unknown, revoked or expired credential.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id

403 FORBIDDEN: see details.reason.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

404 NOT_FOUND: no such resource for this caller.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

429 RATE_LIMITED: the request rate of the API key (details.scope key) or of the account (user) is exhausted for this window, or too many failed authentication attempts came from this IP (no details.scope and no RateLimit headers). Retry after Retry-After seconds.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy , Retry-After

default Error (see ErrorEnvelope and /v1/docs/errors).

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

Delete an upload

DELETE /uploads/{id}

Auth: API key with scope uploads:write, or access token.

Requires uploads:write. Deletes the file now; the upload keeps its metadata with status deleted. Idempotent.

Credits. Free: no credits.

Parameters

Name	In	Type	Description
`id` required	path	`string`	Upload id. An unknown or malformed id is 404.

Responses

204 Deleted.

Headers: X-Request-Id , RateLimit , RateLimit-Policy

400 INVALID_INPUT. A credential sent in the query string is refused before authentication, without RateLimit headers.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

401 UNAUTHORIZED: missing, malformed, unknown, revoked or expired credential.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id

403 FORBIDDEN: see details.reason.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

404 NOT_FOUND: no such resource for this caller.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

429 RATE_LIMITED: the request rate of the API key (details.scope key) or of the account (user) is exhausted for this window, or too many failed authentication attempts came from this IP (no details.scope and no RateLimit headers). Retry after Retry-After seconds.

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy , Retry-After

default Error (see ErrorEnvelope and /v1/docs/errors).

Schema ErrorEnvelope (application/json).

Headers: X-Request-Id , RateLimit , RateLimit-Policy

List uploads

Parameters

Responses

Upload an image

Request body multipart/form-data

Request body application/json

Responses

Start a presigned upload

Request body application/json

Responses

Complete a presigned upload

Parameters

Responses

Get an upload

Parameters

Responses

Delete an upload

Parameters

Responses

Request body `multipart/form-data`

Request body `application/json`

Request body `application/json`