---
title: "Create a screen"
method: POST
path: "/screens"
tags: ["Screens"]
---

# Create a screen

`POST /screens`

Creates a new screen skeleton for the authenticated project.

The created screen has no visual content yet — it is a placeholder you then open in the Qonversion dashboard to lay out components, upload media, and add localisations. Render-time fields (`background`, `default_lang`, `configs`, `content`, `prod_key`, `sandbox_key`) are populated by the dashboard editor, not by this endpoint.

Returns `201 Created` with the newly created `V4Screen` and a `Location` header pointing at `GET /v4/screens/{screen_id}`.

## Request body

- V4ScreenCreate
  - `name` string, required — Human-readable name for the new screen. Must be 1–256 characters.

## Response `201`

Screen created successfully.

- V4Screen — Lean screen representation used on list endpoints. Omits render-time fields (`configs`, `content`, `prod_key`, `sandbox_key`, `used`, etc.) to keep paginated walks cheap. Fetch `V4Screen` via `GET /v4/screens/{screen_id}` for the full render payload.
  - `object` 'screen', required
  - `id` string, required
  - `url` string, required
  - `name` string, required
  - `status` string, required
  - `type` string, nullable
  - `context_key` string, nullable
  - `is_web` boolean, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `background` string, nullable, required — CSS background for the paywall root element.
  - `default_lang` string, nullable, required — Default localisation key. When the SDK can't match the user's locale it falls back to this language.
  - `configs` unknown, required
  - `prod_key` string, nullable, required — SDK integration key used in production builds. Load-bearing — the SDK cannot render the screen without it.
  - `sandbox_key` string, nullable, required — SDK integration key for sandbox / test builds.
  - `content` unknown, required
  - `used` string[], required — UIDs of triggers currently targeting this screen.

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `403` — Insufficient permissions
- `415` — Unsupported Content-Type
- `422` — Unprocessable entity
- `500` — Internal error
- `502` — Upstream service failure
- `504` — Upstream timeout

---

[API](https://skmtc.net/qonversion/apis/qonversion-rest-api-v4.md) · [All operations](https://skmtc.net/qonversion/apis/qonversion-rest-api-v4/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/qonversion/qonversion-rest-api-v4/versions/e3f72cf8951c/schema)