# Catalog API reference

> HTML version: https://storeshot.art/docs/api/catalog/

Static reference data. Contract 1.18.0; base URL `https://api.storeshot.art/v1`. Schemas: https://storeshot.art/docs/api/schemas.md

## GET /devices

**List store screenshot sizes** (operation `listDevices`). No authentication.

App Store and Google Play image sizes Storeshot can generate, including the Google Play 1024×500 feature graphic. No authentication. A deprecated size (`deprecated: true`) is still accepted but never a default; use its `replacedBy`.

**When to use.** To pick `devices` for a screenshot set or the `device` of a generation; most callers can leave `devices` out and get the store defaults.

**Credits.** Free: no credits.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `store` | query | `StoreTarget` | no |  |

**Responses:**

| Status | Description | Schema | Headers |
|---|---|---|---|
| `200` | Device catalogue. | `DeviceList` | `X-Request-Id` |
| `400` | Invalid `store` (`INVALID_INPUT`). | `ErrorEnvelope` | `X-Request-Id` |
| `default` | Error (see ErrorEnvelope and /v1/docs/errors). | `ErrorEnvelope` | `X-Request-Id` |

Example 200 response:

```json
{
  "data": [
    {
      "id": "app_store_1284x2778",
      "store": "app_store",
      "kind": "screenshot",
      "label": "string",
      "deviceHint": "string",
      "width": 1,
      "height": 1,
      "orientations": [],
      "deprecated": true,
      "replacedBy": "google_play_1080x2160"
    }
  ]
}
```

## GET /stores

**List stores** (operation `listStores`). Auth: API key or access token.

The stores Storeshot targets. Any valid API key or access token; no scope required.

**Credits.** Free: no credits.

**Responses:**

| Status | Description | Schema | Headers |
|---|---|---|---|
| `200` | The stores. | `StoreList` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy` |
| `400` | `INVALID_INPUT`. A credential sent in the query string is refused before authentication, without RateLimit headers. | `ErrorEnvelope` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy` |
| `401` | `UNAUTHORIZED`: missing, malformed, unknown, revoked or expired credential. | `ErrorEnvelope` | `X-Request-Id` |
| `403` | `FORBIDDEN`: see `details.reason`. | `ErrorEnvelope` | `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. | `ErrorEnvelope` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy`, `Retry-After` |
| `default` | Error (see ErrorEnvelope and /v1/docs/errors). | `ErrorEnvelope` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy` |

Example 200 response:

```json
{
  "data": [
    {
      "id": "app_store",
      "name": "string",
      "requirementsUrl": "/v1/stores/app_store/requirements"
    }
  ]
}
```

## GET /stores/{store}/requirements

**Get store screenshot requirements** (operation `getStoreRequirements`). Auth: API key or access token.

Formats, counts, sizes or dimension rules per device class, which classes are needed, and the Google Play feature graphic, with the official sources they come from. Each class lists the `GET /devices` sizes it covers and whether they meet the store rules. Any valid API key or access token; no scope required.

**When to use.** Before choosing devices yourself, to check which sizes a store accepts and which device classes it requires.

**Credits.** Free: no credits.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `store` | path | `string` | yes | `app_store` or `google_play`. Anything else is 404. |

**Responses:**

| Status | Description | Schema | Headers |
|---|---|---|---|
| `200` | The requirements. | `StoreRequirements` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy` |
| `400` | `INVALID_INPUT`. A credential sent in the query string is refused before authentication, without RateLimit headers. | `ErrorEnvelope` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy` |
| `401` | `UNAUTHORIZED`: missing, malformed, unknown, revoked or expired credential. | `ErrorEnvelope` | `X-Request-Id` |
| `403` | `FORBIDDEN`: see `details.reason`. | `ErrorEnvelope` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy` |
| `404` | `NOT_FOUND`: no such resource for this caller. | `ErrorEnvelope` | `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. | `ErrorEnvelope` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy`, `Retry-After` |
| `default` | Error (see ErrorEnvelope and /v1/docs/errors). | `ErrorEnvelope` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy` |

Example 200 response:

```json
{
  "store": "app_store",
  "name": "string",
  "screenshots": {
    "formats": [
      "image/png"
    ],
    "alpha": true,
    "maxFileBytes": 1,
    "count": {
      "minTotal": 0,
      "maxPerDeviceClass": 1
    },
    "sources": [
      "apple_screenshot_specs"
    ]
  },
  "deviceClasses": [
    {
      "id": "phone",
      "family": "iphone",
      "label": "string",
      "requirement": "required",
      "count": {
        "min": 0,
        "max": 1
      },
      "maxFileBytes": 1,
      "acceptedSizes": [
        {}
      ],
      "rules": {
        "minEdge": 1,
        "maxEdge": 1,
        "maxAspectRatio": 0,
        "exactAspectRatio": "string",
        "recommendedAspectRatios": []
      },
      "sources": [
        "apple_screenshot_specs"
      ],
      "devices": [
        {}
      ]
    }
  ],
  "requiredGroups": [
    {
      "when": "app runs on iPad",
      "anyOf": [
        "string"
      ],
      "sources": [
        "apple_screenshot_specs"
      ]
    }
  ],
  "featureGraphic": {
    "width": 1,
    "height": 1,
    "formats": [
      "image/png"
    ],
    "alpha": true,
    "maxFileBytes": 1,
    "required": true,
    "sources": [
      "apple_screenshot_specs"
    ],
    "device": "google_play_1024x500"
  },
  "sources": [
    {
      "id": "apple_screenshot_specs",
      "title": "string",
      "url": "https://example.com",
      "checkedOn": "string"
    }
  ]
}
```