Builder API

Create App Store screenshots programmatically. Send natural language messages, get back canvas state JSON with device mockups, backgrounds, and text.

Authentication

All API requests require a Bearer token in the Authorization header. Create API keys in Settings → API Keys.

Authorization: Bearer sk_live_your_key_here

Base URL

https://appscreenshotstudio.com/api/v1

Endpoints

POST/projects

Create a new builder project.

Request body

{
  "device_id": "iphone-6.9",   // or "android-phone"
  "name": "My App Screenshots" // optional
}

Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "My App Screenshots",
    "device_id": "iphone-6.9",
    "canvas_state": { "cards": [], ... }
  },
  "credits_remaining": 74
}

GET/projects

List all your builder projects.

Response

{
  "success": true,
  "data": [ ... ],
  "credits_remaining": 74
}

GET/projects/:id

Get a project with its full canvas state.

Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "canvas_state": { "cards": [...], ... },
    ...
  },
  "credits_remaining": 74
}

POST/projects/:id/chat

Send a message to build screenshots. Costs 1 credit per message.

Request body

{
  "message": "Create 5 App Store screenshots for a fitness app called FitPro",
  "images": [                          // optional
    { "dataUrl": "data:image/png;base64,..." }
  ],
  "selected_card_indices": [0, 1]      // optional
}

Response

{
  "success": true,
  "data": {
    "message": "Created 5 cards with ...",
    "operations": [ ... ],
    "canvas_state": { "cards": [...], ... },
    "suggestions": ["Add ratings", "Change colors", ...]
  },
  "credits_remaining": 73
}

PATCH/projects/:id

Update a project's name, device, or canvas state.

Request body

{
  "name": "Updated Name",             // optional
  "device_id": "android-phone",       // optional
  "canvas_state": { ... }             // optional
}

DELETE/projects/:id

Delete a project.

Response

{ "success": true }

POST/projects/:id/render

Render all cards as PNG images. Free — no credit cost. No request body needed.

Response

{
  "success": true,
  "data": {
    "images": [
      { "card_index": 0, "url": "https://...png", "width": 1260, "height": 2736 },
      { "card_index": 1, "url": "https://...png", "width": 1260, "height": 2736 }
    ]
  },
  "credits_remaining": 68
}

Rate Limits

Rate limit info is included in response headers.

Endpoint	Limit
POST /projects/:id/chat	60 requests / 5 minutes
All other endpoints	120 requests / minute

Errors

{
  "success": false,
  "error": "Human-readable message",
  "code": "ERROR_CODE"
}

Code	HTTP	Meaning
UNAUTHORIZED	401	Invalid or revoked API key
NO_CREDITS	402	Insufficient credits
NOT_FOUND	404	Project not found or not yours
VALIDATION_ERROR	400	Invalid request body

Quick Start

# 1. Create a project
curl -X POST https://appscreenshotstudio.com/api/v1/projects \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"device_id": "iphone-6.9", "name": "FitPro"}'

# 2. Build screenshots via chat (1 credit per message)
curl -X POST https://appscreenshotstudio.com/api/v1/projects/PROJECT_ID/chat \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"message": "Create 5 screenshots for a fitness app"}'

# 3. Iterate
curl -X POST .../chat \
  -d '{"message": "Make the backgrounds darker and add star ratings"}'

# 4. Render as PNGs (free)
curl -X POST https://appscreenshotstudio.com/api/v1/projects/PROJECT_ID/render \
  -H "Authorization: Bearer sk_live_your_key"