Projects API reference - StoreShot docs

List projects

GET /projects

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

Requires generations:read or generations:write. Projects of the account (every API key and environment), most recently updated 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 projects.

Schema ProjectList (application/json).

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

Example 200 response

{
  "data": [
    {
      "id": "2a4b6c8d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
      "name": "Trailmate",
      "description": "Offline hiking maps",
      "store": "app_store",
      "palette": [
        {
          "hex": "#0F766E",
          "name": "Teal"
        }
      ],
      "logo": null,
      "counts": {
        "generations": 3,
        "screenshotSets": 1
      },
      "preview": null,
      "createdAt": "2026-10-29T10:00:00.000Z",
      "updatedAt": "2026-10-29T10:05: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

Create a project

POST /projects

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

Requires generations:write. A project groups the generations and screenshot sets of one app (name, store, palette, logo). Add items with POST /projects/{id}/items or projectId when creating them. At most 200 projects per account (403 FORBIDDEN, details.reason project_limit_reached).

Credits. Free: no credits.

Request body `application/json`

Required. Schema CreateProjectRequest.

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

Example request body

{
  "name": "Trailmate",
  "description": "Offline hiking maps",
  "store": "app_store",
  "palette": [
    {
      "hex": "#0F766E",
      "name": "Teal"
    }
  ]
}

Responses

201 Created.

Schema Project (application/json).

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

Example 201 response

{
  "id": "2a4b6c8d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
  "name": "Trailmate",
  "description": "Offline hiking maps",
  "store": "app_store",
  "palette": [
    {
      "hex": "#0F766E",
      "name": "Teal"
    }
  ],
  "logo": null,
  "counts": {
    "generations": 3,
    "screenshotSets": 1
  },
  "preview": null,
  "createdAt": "2026-10-29T10:00:00.000Z",
  "updatedAt": "2026-10-29T10:05: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

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

Get a project

GET /projects/{id}

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

Requires generations:read or generations:write. List its items with GET /generations?projectId= and GET /screenshot-sets?projectId=.

Credits. Free: no credits.

Parameters

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

Responses

200 The project.

Schema Project (application/json).

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

Example 200 response

{
  "id": "2a4b6c8d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
  "name": "Trailmate",
  "description": "Offline hiking maps",
  "store": "app_store",
  "palette": [
    {
      "hex": "#0F766E",
      "name": "Teal"
    }
  ],
  "logo": null,
  "counts": {
    "generations": 3,
    "screenshotSets": 1
  },
  "preview": null,
  "createdAt": "2026-10-29T10:00:00.000Z",
  "updatedAt": "2026-10-29T10:05: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 a project

DELETE /projects/{id}

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

Requires generations:write. Its generations and screenshot sets are kept, in no project; its logo is deleted.

Credits. Free: no credits.

Parameters

Name	In	Type	Description
`id` required	path	`string`	Project 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

Update a project

PATCH /projects/{id}

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

Requires generations:write. Changes only the fields sent: palette: [] clears the palette, logo: null removes the logo.

Credits. Free: no credits.

Parameters

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

Request body `application/json`

Required. Schema UpdateProjectRequest.

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

Example request body

{
  "name": "Trailmate 2",
  "logo": null
}

Responses

200 The updated project.

Schema Project (application/json).

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

Example 200 response

{
  "id": "2a4b6c8d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
  "name": "Trailmate",
  "description": "Offline hiking maps",
  "store": "app_store",
  "palette": [
    {
      "hex": "#0F766E",
      "name": "Teal"
    }
  ],
  "logo": null,
  "counts": {
    "generations": 3,
    "screenshotSets": 1
  },
  "preview": null,
  "createdAt": "2026-10-29T10:00:00.000Z",
  "updatedAt": "2026-10-29T10:05: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

Add items to a project

POST /projects/{id}/items

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

Requires generations:write. Puts standalone generations and whole screenshot sets in this project; an item in another project moves here (an item is in one project at most). Repeating it changes nothing. An image of a screenshot set is in the project of its set and cannot be added alone.

Credits. Free: no credits.

Parameters

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

Request body `application/json`

Required. Schema ProjectItemsRequest.

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.

Example request body

{
  "generationIds": [
    "0b8e7a52-41c6-4f38-9d0e-7f6a1c2b3d4e"
  ]
}

Responses

200 The items are in the project.

Schema ProjectItemsAdded (application/json).

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

Example 200 response

{
  "projectId": "7d0e1a52-3c4b-4f6e-9a8d-2b1c0f9e8a7d",
  "added": 0
}

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

Remove items from a project

POST /projects/{id}/items/remove

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

Requires generations:write. Takes the items out of this project (they are kept, in no project). Items that are not in this project are left alone.

Credits. Free: no credits.

Parameters

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

Request body `application/json`

Required. Schema ProjectItemsRequest.

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.

Example request body

{
  "generationIds": [
    "0b8e7a52-41c6-4f38-9d0e-7f6a1c2b3d4e"
  ]
}

Responses

200 The items left it.

Schema ProjectItemsRemoved (application/json).

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

Example 200 response

{
  "projectId": "7d0e1a52-3c4b-4f6e-9a8d-2b1c0f9e8a7d",
  "removed": 0
}

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 projects

Parameters

Responses

Create a project

Request body application/json

Responses

Get a project

Parameters

Responses

Delete a project

Parameters

Responses

Update a project

Parameters

Request body application/json

Responses

Add items to a project

Parameters

Request body application/json

Responses

Remove items from a project

Parameters

Request body application/json

Responses

Request body `application/json`

Request body `application/json`

Request body `application/json`

Request body `application/json`