> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# ScreenshotOne API reference

> API reference for ScreenshotOne: every `screenshotone.api.*` operation with input and output types.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Devices

### list

`devices.list`

List device presets. User agent strings are not stored.

**Risk:** `read`

```ts theme={null}
await corsair.screenshotone.api.devices.list({});
```

**Input:** *empty object*

GET /devices. Stores id, name, width, and height.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `devices` | `object[]` | Yes | — |

> [accordion] devices full type
>
> ```ts theme={null}
> {
>   id: string,
>   name?: string,
>   width?: number,
>   height?: number
> }[]
> ```

***

## Shots

### animate

`shots.animate`

Record a page as a video or GIF (default or scroll scenario). Returns a link to the file. Spends a request from the plan.

**Risk:** `write`

```ts theme={null}
await corsair.screenshotone.api.shots.animate({ url: 'https://example.com', scenario: 'scroll' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `viewport_width` | `number` | No | — |
| `viewport_height` | `number` | No | — |
| `device_scale_factor` | `number` | No | — |
| `viewport_device` | `string` | No | — |
| `viewport_mobile` | `boolean` | No | — |
| `delay` | `number` | No | — |
| `wait_until` | `(load \| domcontentloaded \| networkidle0 \| networkidle2)[]` | No | — |
| `timeout` | `number` | No | — |
| `block_ads` | `boolean` | No | — |
| `block_cookie_banners` | `boolean` | No | — |
| `block_trackers` | `boolean` | No | — |
| `block_chats` | `boolean` | No | — |
| `dark_mode` | `boolean` | No | — |
| `url` | `string` | Yes | — |
| `scenario` | `default \| scroll` | No | — |
| `duration` | `number` | No | — |
| `format` | `mp4 \| mov \| avi \| webm \| gif` | No | — |

GET /animate with response\_type=json. scenario is default or scroll, duration 1-30 s, format mp4, mov, avi, webm or gif. Returns screenshotUrl.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `screenshotUrl` | `string` | Yes | — |
| `cacheUrl` | `string` | No | — |

***

### bulk

`shots.bulk`

Build up to 20 screenshot requests at once; with execute true they run now (one plan request each) and each url gets its status.

**Risk:** `write`

```ts theme={null}
await corsair.screenshotone.api.shots.bulk({ urls: ['https://example.com'], options: { format: 'png' } });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `urls` | `string[]` | Yes | — |
| `execute` | `boolean` | No | — |
| `options` | `object` | No | — |

POST /bulk. options apply to every url. Returns the /take url built for each request with access\_key removed; with execute true (default false) the requests run now and results gives each one's status.

> [accordion] options full type
>
> ```ts theme={null}
> {
>   viewport_width?: number,
>   viewport_height?: number,
>   device_scale_factor?: number,
>   viewport_device?: string,
>   viewport_mobile?: boolean,
>   delay?: number,
>   wait_until?: (load | domcontentloaded | networkidle0 | networkidle2)[],
>   timeout?: number,
>   block_ads?: boolean,
>   block_cookie_banners?: boolean,
>   block_trackers?: boolean,
>   block_chats?: boolean,
>   dark_mode?: boolean,
>   format?: png | jpeg | jpg | webp | gif | jp2 | tiff | avif | heif | pdf | html | markdown,
>   full_page?: boolean,
>   selector?: string,
>   image_quality?: number,
>   omit_background?: boolean,
>   cache?: boolean,
>   cache_ttl?: number
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `urls` | `string[]` | Yes | — |
| `results` | `object[]` | No | — |

> [accordion] results full type
>
> ```ts theme={null}
> {
>   url: string,
>   isSuccessful?: boolean,
>   status?: number
> }[]
> ```

***

### take

`shots.take`

Screenshot a url, HTML or Markdown as an image or PDF, with viewport, device, full page, selector, blocking and caching options. Returns a link to the file. Spends a request from the plan.

**Risk:** `write`

```ts theme={null}
await corsair.screenshotone.api.shots.take({ url: 'https://example.com', format: 'png', full_page: true, block_cookie_banners: true });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `viewport_width` | `number` | No | — |
| `viewport_height` | `number` | No | — |
| `device_scale_factor` | `number` | No | — |
| `viewport_device` | `string` | No | — |
| `viewport_mobile` | `boolean` | No | — |
| `delay` | `number` | No | — |
| `wait_until` | `(load \| domcontentloaded \| networkidle0 \| networkidle2)[]` | No | — |
| `timeout` | `number` | No | — |
| `block_ads` | `boolean` | No | — |
| `block_cookie_banners` | `boolean` | No | — |
| `block_trackers` | `boolean` | No | — |
| `block_chats` | `boolean` | No | — |
| `dark_mode` | `boolean` | No | — |
| `format` | `png \| jpeg \| jpg \| webp \| gif \| jp2 \| tiff \| avif \| heif \| pdf \| html \| markdown` | No | — |
| `full_page` | `boolean` | No | — |
| `selector` | `string` | No | — |
| `image_quality` | `number` | No | — |
| `omit_background` | `boolean` | No | — |
| `cache` | `boolean` | No | — |
| `cache_ttl` | `number` | No | — |
| `url` | `string` | No | — |
| `html` | `string` | No | — |
| `markdown` | `string` | No | — |

POST /take with a JSON body and response\_type=json, so long html or markdown fits. Pass exactly one of url, html or markdown. Options include format (png, jpg, webp, pdf and more), full\_page, selector, viewport\_width/height, viewport\_device (an id from devices.list), delay, wait\_until, the block\_\* switches, dark\_mode and cache/cache\_ttl. Returns screenshotUrl, and cacheUrl when cache is true. The target URL is not stored.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `screenshotUrl` | `string` | Yes | — |
| `cacheUrl` | `string` | No | — |

***

## Usage

### get

`usage.get`

Read the current plan usage and request bucket.

**Risk:** `read`

```ts theme={null}
await corsair.screenshotone.api.usage.get({});
```

**Input:** *empty object*

GET /usage. Stores total, available, used, and the concurrency bucket on id plan.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `usage` | `object` | Yes | — |

> [accordion] usage full type
>
> ```ts theme={null}
> {
>   id: string,
>   total?: number,
>   available?: number,
>   used?: number,
>   concurrencyLimit?: number,
>   concurrencyRemaining?: number,
>   concurrencyReset?: number
> }
> ```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.