> ## Documentation Index > Fetch the complete documentation index at: https://docs.scrnshot.site/llms.txt > Use this file to discover all available pages before exploring further. # Capture a screenshot > Renders `url` and returns a hosted image. Every request — cache hit or miss — counts against the monthly quota. Results are cached for ~15 minutes per unique combination of URL and capture options; Pro plans can force a fresh render with `fresh: true`. See [Caching & fresh](/guides/caching-and-fresh) for details. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/screenshots openapi: 3.1.0 info: title: scrnshot API version: 1.0.0 summary: Programmatic screenshot capture for developers. description: | scrnshot renders a URL and returns a hosted image. Authenticate with an API key (`X-API-Key`) for the endpoints under `/v1/screenshots` and `/v1/usage`. API-key management (`/v1/keys`) and billing endpoints use dashboard session cookies instead and are documented here for completeness — they are not part of the programmatic integration surface. Quotas are monthly (Free: 100/mo, Pro: 5,000/mo). Independently, requests are rate-limited per minute (Free: 5/min, Pro: 60/min). Exceeding the monthly quota returns `402`; exceeding the per-minute rate limit returns `429`. servers: - url: https://api.scrnshot.site description: Production security: - ApiKeyAuth: [] tags: - name: Screenshots description: Capture, list, and delete screenshots. - name: Usage description: Quota and rate-limit consumption. - name: API Keys description: | Dashboard-only. Authenticated with a session cookie, not an API key — a key cannot be used to mint or revoke other keys. - name: Billing description: Dashboard-only. Authenticated with a session cookie. - name: Demo description: | Unauthenticated, IP-rate-limited endpoint that powers the live demo on scrnshot.site. Not intended for integration — use `/v1/screenshots` with an API key instead. paths: /v1/screenshots: post: tags: - Screenshots summary: Capture a screenshot description: | Renders `url` and returns a hosted image. Every request — cache hit or miss — counts against the monthly quota. Results are cached for ~15 minutes per unique combination of URL and capture options; Pro plans can force a fresh render with `fresh: true`. See [Caching & fresh](/guides/caching-and-fresh) for details. operationId: createScreenshot requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateScreenshotRequest' examples: minimal: summary: Minimal request value: url: https://example.com full: summary: All options value: url: https://example.com format: webp width: 1440 height: 900 full_page: true quality: 90 fresh: true responses: '201': description: Screenshot captured (or served from cache). content: application/json: schema: $ref: '#/components/schemas/CreateScreenshotResponse' example: id: 4821 image_url: https://cdn.scrnshot.site/a1b2c3d4.png cached: false expires_at: '2026-08-19T12:00:00Z' quota: used: 42 limit: 5000 '400': description: >- Invalid request — missing/malformed `url`, or an option not permitted on the caller's plan (e.g. an unsupported `format`, dimensions above the plan ceiling, `fresh` or `device_scale` on Free). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: format webp is not available on the free plan '401': $ref: '#/components/responses/Unauthorized' '402': description: >- Monthly quota exhausted. Upgrade to Pro or wait for the plan's reset date (see `GET /v1/usage`). content: application/json: schema: $ref: '#/components/schemas/QuotaExceededResponse' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' security: - ApiKeyAuth: [] components: schemas: CreateScreenshotRequest: type: object required: - url properties: url: type: string format: uri description: The page to capture. example: https://example.com format: type: string enum: - png - jpeg - webp default: png description: Output image format. `webp` is Pro-only. width: type: integer minimum: 1 description: >- Viewport width in pixels. Defaults to 1920, capped to the plan's maximum (Free 1920, Pro 3840). height: type: integer minimum: 1 description: >- Viewport height in pixels. Defaults to 1080, capped to the plan's maximum (Free 1080, Pro 2160). full_page: type: boolean default: false description: >- Capture the full scrollable page instead of just the viewport. Available on Free and Pro. quality: type: integer minimum: 1 maximum: 100 default: 80 description: Compression quality for `jpeg`/`webp` output. fresh: type: boolean default: false description: Bypass the response cache and force a new render. Pro-only. CreateScreenshotResponse: type: object required: - image_url - cached - expires_at - quota properties: id: type: - integer - 'null' description: | Present only when the capture is backed by a listable/deletable database row (Pro plan). Free-plan captures still return an `image_url` but omit `id` — there is nothing to pass to `DELETE /v1/screenshots/{id}` or expect back from `GET /v1/screenshots`. image_url: type: string format: uri description: Hosted URL of the captured image. cached: type: boolean description: >- True if this response was served from the ~15-minute result cache rather than a fresh render. expires_at: type: string format: date-time description: >- When the image is purged per the plan's retention window (Free 7 days, Pro 30 days). quota: type: object required: - used - limit properties: used: type: integer description: >- Screenshots consumed in the current monthly period, including this request. limit: type: integer description: Monthly quota for the account's plan. ErrorResponse: type: object required: - error properties: error: type: string description: Human-readable error message. QuotaExceededResponse: type: object required: - error - plan - used - limit properties: error: type: string example: monthly quota exceeded plan: type: string enum: - free - pro used: type: integer limit: type: integer resets_at: type: string format: date-time RateLimitedResponse: type: object required: - message - success - limit - used - remaining - reset_time properties: message: type: string example: Rate limit exceeded success: type: boolean example: false limit: type: integer used: type: integer remaining: type: integer reset_time: type: integer description: Unix timestamp when the rate-limit window resets. plan: type: string responses: Unauthorized: description: Missing, malformed, or revoked credentials. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: unauthorized RateLimited: description: >- Per-minute rate limit exceeded (Free 5/min, Pro 60/min). Back off and retry using `reset_time`. content: application/json: schema: $ref: '#/components/schemas/RateLimitedResponse' ServerError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: | Programmatic auth for the `/v1/screenshots` and `/v1/usage` endpoints. Create a key from the dashboard (`POST /v1/keys`); the plaintext value is shown once at creation. ````