Screenshot Design API#

The Design API accepts raw app screenshots and returns styled, App Store-ready images. This is the endpoint used by the Blitz integration and any external tool that captures screenshots locally and wants Stora to handle the design step.

No cloud device needed — this endpoint handles only the design step, not app capture.

Create Design Job#

POST /v1/design — Requires authentication

Accepts raw screenshots as base64-encoded PNGs, creates an async design job, and returns a job ID for polling.

Request Body#

| Name | Type | Required | Description | |------|------|----------|-------------| | images | array | Yes | Array of image objects (max 10). | | images[].data | string | Yes | Base64-encoded PNG data (max 10 MB per image). | | images[].screen | string | Yes | Screen name (e.g. "home", "settings", "onboarding"). | | images[].device | string | No | Device identifier. Defaults to iphone-16-pro. | | project_name | string | Yes | App name — used for tagline generation and design context. | | bundle_id | string | No | Bundle identifier (e.g. com.example.app). | | template | string | No | Design template. Defaults to default. | | webhook_url | string | No | URL to POST when the job completes or fails. |

Example Request#

curl -X POST \
  -H "Authorization: Bearer sk_stora_..." \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      { "data": "<base64 PNG>", "screen": "home", "device": "iphone-16-pro" },
      { "data": "<base64 PNG>", "screen": "profile" }
    ],
    "project_name": "MyApp",
    "bundle_id": "com.example.myapp"
  }' \
  https://www.stora.sh/api/v1/design

Response (202 Accepted)#

{
  "job_id": "design_abc123def456",
  "status": "queued",
  "poll_url": "https://www.stora.sh/api/v1/design/design_abc123def456"
}

Design jobs typically take 30–60 seconds depending on the number of images.

Get Design Job#

GET /v1/design/:job_id — Requires authentication

Returns the current status of a design job. Poll this endpoint until status is completed or failed.

Path Parameters#

| Name | Type | Required | Description | |------|------|----------|-------------| | job_id | string | Yes | The design job ID returned by the create endpoint. |

Response (Queued/Processing)#

{
  "job_id": "design_abc123def456",
  "status": "processing",
  "created_at": "2026-04-03T12:00:00Z",
  "project_name": "MyApp",
  "input_count": 2
}

Response (Completed)#

{
  "job_id": "design_abc123def456",
  "status": "completed",
  "created_at": "2026-04-03T12:00:00Z",
  "completed_at": "2026-04-03T12:00:45Z",
  "project_name": "MyApp",
  "input_count": 2,
  "output_urls": [
    "https://www.stora.sh/screenshots/design_abc123def456/screenshot-1.png",
    "https://www.stora.sh/screenshots/design_abc123def456/screenshot-2.png"
  ]
}

Response (Failed)#

{
  "job_id": "design_abc123def456",
  "status": "failed",
  "created_at": "2026-04-03T12:00:00Z",
  "project_name": "MyApp",
  "input_count": 2,
  "error": "Render produced no screenshots"
}

Status Values#

| Status | Description | |---|---| | queued | Job is waiting to be processed. | | processing | The design agent is generating styled screenshots. | | completed | All styled screenshots are ready. Check output_urls. | | failed | Something went wrong. Check the error field. |

Webhooks#

If you provide a webhook_url in the create request, Stora will POST to that URL when the job finishes:

Completion Webhook#

{
  "job_id": "design_abc123def456",
  "status": "completed",
  "output_urls": [
    "https://www.stora.sh/screenshots/design_abc123def456/screenshot-1.png",
    "https://www.stora.sh/screenshots/design_abc123def456/screenshot-2.png"
  ]
}

Failure Webhook#

{
  "job_id": "design_abc123def456",
  "status": "failed",
  "error": "Render produced no screenshots"
}

Webhook delivery is best-effort. If your endpoint is unreachable, the webhook will not be retried. Always poll as a fallback.

Rate Limits#

The design endpoint is limited to 10 requests per minute per API key.

Design Pipeline#

Under the hood, each design job runs through these stages:

1. Domain detection — Categorizes your app (fitness, finance, social, etc.) for tailored design direction.
2. App intelligence — Extracts features and key mechanisms from the app name and context.
3. Tagline generation — Creates marketing headlines and subtitles for each screenshot.
4. Composition planning — Plans layout, typography, and color for visual variety across the set.
5. Code generation — Generates HTML/CSS design code for each screenshot using AI.
6. Rendering — Renders the designs to PNG at App Store resolution via headless Chromium.

Limitations (v1)#

• iPhone only (iPhone 16 Pro). iPad and Android support coming in v2.
• Default template only. Custom template selection coming in v2.
• No ASO metadata generation (use the Metadata API separately).