# appscreenshotapi full agent documentation

Canonical site: https://appscreenshotapi.com/
API base URL: https://api.appscreenshotapi.com
OpenAPI: https://appscreenshotapi.com/openapi.json
Short agent index: https://appscreenshotapi.com/llms.txt

appscreenshotapi generates store-ready App Store and Google Play screenshot sets
from JSON and real app captures. The renderer composites supplied screenshots;
it does not hallucinate app UI. Optional BYOK AI can draft an editable render
request, but final pixels are deterministic.

## Authentication

Use a Bearer token:

Authorization: Bearer $APPSCREENSHOTAPI_KEY

Recommended environment variable: APPSCREENSHOTAPI_KEY.
Live keys start with asa_live_. Test keys start with asa_test_ and render
watermarked output.

Never print keys in terminal logs, CI output, screenshots, commits, or issue
comments.

## Main render endpoint

POST https://api.appscreenshotapi.com/v1/renders

Required behavior for agents:

1. Send Content-Type: application/json.
2. Send an Idempotency-Key for any retryable job.
3. Provide screenshot input as URL or base64.
4. Read the response status and lint array.
5. Revise and rerender if any lint finding has status=fail.
6. Stop for human approval before payment or store upload.

Minimal request:

```json
{
  "canvas": { "preset": "appstore.iphone_6_9" },
  "preset": "aurora-midnight",
  "slides": [
    {
      "headline": { "lines": ["Numbers you can", "act on"], "accent": "act on" },
      "screenshot": { "url": "https://example.com/captures/home.png" }
    }
  ]
}
```

Response includes:

- id
- status
- images[] with CDN URLs, width, and height
- lint[] with rule, authority, status, and detail
- screenshots_used or credits_used, depending on API version
- expires_at

## Async jobs

For large matrices, set async=true. The API returns 202, a render id, and a
polling URL. Poll GET /v1/renders/{id} until status is succeeded or failed.
Use webhook_url when your workflow should receive a signed completion callback,
or poll when a build runner needs to wait inline.

## Output formats

Use output.format=images for direct CDN image URLs.
Use output.format=fastlane_zip for a locale-folder archive that can be used with
Fastlane deliver workflows.

One final exported image consumes one screenshot from the account balance.

## Billing behavior for agents

Free accounts include 3 watermarked screenshots.
Screenshot packs are $18 for 1,000 screenshots.
Bulk screenshot packs are $48 for 3,500 screenshots.

If a render exceeds the available balance, the API returns HTTP 402 with a
billing_url. Agents must show that URL to the human and wait for explicit
approval before payment. Do not autonomously pay unless the user has explicitly
authorized that exact purchase flow.

## Optional brief endpoint

POST https://api.appscreenshotapi.com/v1/briefs

This endpoint accepts a plain-language brief plus a required BYOK llm object and
returns an editable /v1/renders request body. The supplied model key is used for
one upstream call and is not stored. The resulting spec is validated before it is
returned.

Use /v1/briefs to draft a starting point. Use /v1/renders to produce final
screenshots.

## Store safety rules

- Use real app UI captures.
- Do not claim "best", "#1", "free", discounts, or rankings unless the app can
  substantiate them and store rules allow it.
- Treat official lint failures as blockers.
- Treat heuristic warnings as revision suggestions.
- Keep App Store Connect and Google Play uploads as explicit human approvals.

## Discovery links

- Docs: https://appscreenshotapi.com/docs/
- Markdown docs: https://appscreenshotapi.com/docs/index.md
- Pricing: https://appscreenshotapi.com/pricing/
- Options: https://appscreenshotapi.com/options/
- Gallery: https://appscreenshotapi.com/gallery/
- Support: https://appscreenshotapi.com/support/
- Status: https://appscreenshotapi.com/status/