---
title: "Upload screens captured from the simulator"
method: POST
path: "/apps/{id}/screens"
tags: ["Screens"]
---

# Upload screens captured from the simulator

`POST /apps/{id}/screens`

## Request

- Base URL: `https://pagefully.com/api/v1`
- URL: `https://pagefully.com/api/v1/apps/{id}/screens`
- Auth: HTTP bearer

Each is a PNG or a JPEG, 8 MB at most, at a size Apple takes for an iPhone or iPad screenshot, upright or on its side. As multipart form data, each file part a screen (the field is named `file`), or as JSON. 10 in one call at most. Every file is checked before any is kept. A screen is kept beside the listing's screenshots, tagged as uploaded, and takes one of the 10 places the app's screens have for its device: the lowest free one, or `position`. The same file sent twice is kept once. Nothing is sent to Apple.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `screens` object[], required
    - `data` string, required: The file in base64, bare or as a data: address.
    - `name` string
    - `position` integer

## Response `200`

Every file was uploaded before.

- ScreensKept
  - `added` Screen[], required
    - `id` string, nullable, required: An uploaded screen's id. Null for one of the listing's own.
    - `source` 'listing' | 'uploaded', required
    - `device` 'iphone' | 'ipad', required
    - `position` integer, required: What a page's screenshot names to show it.
    - `width` integer, nullable, required
    - `height` integer, nullable, required
    - `name` string, nullable, required
    - `uploaded_at` string, nullable, required
    - `selectable` boolean, required: False for an uploaded screen whose place the listing has since taken.
    - `url` string, nullable, required: The picture at display size.
    - `read` object, nullable, required: What Pagefully read on the picture. Null until it has been studied.
      - `has_words` boolean, required: False for a bare app screen.
      - `headline` string, required
      - `subline` string, required
      - `kicker` string, required
      - `design` 'ours' | 'theirs', required: ours: a page puts this screen in Pagefully's own design. theirs: a page keeps the developer's design and changes only its words.
  - `already` Screen[], required: Files uploaded before, kept once.
    - `id` string, nullable, required: An uploaded screen's id. Null for one of the listing's own.
    - `source` 'listing' | 'uploaded', required
    - `device` 'iphone' | 'ipad', required
    - `position` integer, required: What a page's screenshot names to show it.
    - `width` integer, nullable, required
    - `height` integer, nullable, required
    - `name` string, nullable, required
    - `uploaded_at` string, nullable, required
    - `selectable` boolean, required: False for an uploaded screen whose place the listing has since taken.
    - `url` string, nullable, required: The picture at display size.
    - `read` object, nullable, required: What Pagefully read on the picture. Null until it has been studied.
      - `has_words` boolean, required: False for a bare app screen.
      - `headline` string, required
      - `subline` string, required
      - `kicker` string, required
      - `design` 'ours' | 'theirs', required: ours: a page puts this screen in Pagefully's own design. theirs: a page keeps the developer's design and changes only its words.
  - `screens` Screen[], required
    - `id` string, nullable, required: An uploaded screen's id. Null for one of the listing's own.
    - `source` 'listing' | 'uploaded', required
    - `device` 'iphone' | 'ipad', required
    - `position` integer, required: What a page's screenshot names to show it.
    - `width` integer, nullable, required
    - `height` integer, nullable, required
    - `name` string, nullable, required
    - `uploaded_at` string, nullable, required
    - `selectable` boolean, required: False for an uploaded screen whose place the listing has since taken.
    - `url` string, nullable, required: The picture at display size.
    - `read` object, nullable, required: What Pagefully read on the picture. Null until it has been studied.
      - `has_words` boolean, required: False for a bare app screen.
      - `headline` string, required
      - `subline` string, required
      - `kicker` string, required
      - `design` 'ours' | 'theirs', required: ours: a page puts this screen in Pagefully's own design. theirs: a page keeps the developer's design and changes only its words.
  - `next` string, required

## Other responses

- `201`: Kept.
- `400`: The request could not be read: a body that is not a JSON object, or a field missing or of the wrong kind.
- `401`: No token, or one that is not valid or has been revoked.
- `403`: The token's scope does not allow this call.
- `404`: Not found on this workspace.
- `409`: `not_ready`: the app's listing has not been read yet.
- `413`: `too_large`: a file or the call is over the limit.
- `422`: Understood, and refused by the product. The message says why, in a sentence that can be shown as it is.
- `429`: Too many calls: 120 requests a minute for a token, and 20 generation starts an hour. `retry_after` is seconds.

---

[API](https://skmtc.dev/pagefully/apis/pagefully-api.md) · [All operations](https://skmtc.dev/pagefully/apis/pagefully-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pagefully/apis/pagefully-api/revisions/60e17ce09d31?raw)