> ## 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.

# Pexels API reference

> API reference for the Pexels plugin in Corsair: every `pexels.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!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).

## Collections

### list

`collections.list`

List the collections of the API key

**Risk:** `read`

```ts theme={null}
await corsair.pexels.api.collections.list({ per_page: 25 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `page` | `number` | No | Page number |
| `per_page` | `number` | No | Results per page, at most 80 |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `collections` | `object[]` | Yes | Collections on this page |
| `page` | `number \| null` | No | Page returned |
| `per_page` | `number \| null` | No | Results per page |
| `total_results` | `number \| null` | No | Total collections |
| `next_page` | `string \| null` | No | URL of the next page |
| `prev_page` | `string \| null` | No | URL of the previous page |

> [accordion] collections full type
>
> ```ts theme={null}
> {
>   id: string,
>   title?: string | null,
>   description?: string | null,
>   private?: boolean | null,
>   media_count?: number | null,
>   photos_count?: number | null,
>   videos_count?: number | null
> }[]
> ```

***

### listFeatured

`collections.listFeatured`

List the featured collections

**Risk:** `read`

```ts theme={null}
await corsair.pexels.api.collections.listFeatured({ per_page: 25 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `page` | `number` | No | Page number |
| `per_page` | `number` | No | Results per page, at most 80 |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `collections` | `object[]` | Yes | Featured collections on this page |
| `page` | `number \| null` | No | Page returned |
| `per_page` | `number \| null` | No | Results per page |
| `total_results` | `number \| null` | No | Total featured collections |
| `next_page` | `string \| null` | No | URL of the next page |
| `prev_page` | `string \| null` | No | URL of the previous page |

> [accordion] collections full type
>
> ```ts theme={null}
> {
>   id: string,
>   title?: string | null,
>   description?: string | null,
>   private?: boolean | null,
>   media_count?: number | null,
>   photos_count?: number | null,
>   videos_count?: number | null
> }[]
> ```

***

### listMedia

`collections.listMedia`

List the photos and videos of a collection, filtered by type

**Risk:** `read`

```ts theme={null}
await corsair.pexels.api.collections.listMedia({ collectionId: "9nkrlyb", type: "photos", sort: "desc", per_page: 25 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `collectionId` | `string` | Yes | Collection id |
| `type` | `photos \| videos` | No | Only photos or only videos; both when omitted |
| `sort` | `asc \| desc` | No | Order by when the item was added |
| `page` | `number` | No | Page number |
| `per_page` | `number` | No | Results per page, at most 80 |

Returns photos and videos together unless type is set; each item is a photo or video object with a type of Photo or Video.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `media` | `object[]` | Yes | Media items on this page |
| `page` | `number \| null` | No | Page returned |
| `per_page` | `number \| null` | No | Results per page |
| `total_results` | `number \| null` | No | Total media items |
| `next_page` | `string \| null` | No | URL of the next page |
| `prev_page` | `string \| null` | No | URL of the previous page |

> [accordion] media full type
>
> ```ts theme={null}
> {
>   id?: number | null,
>   width?: number | null,
>   height?: number | null,
>   url?: string | null,
>   photographer?: string | null,
>   photographer_url?: string | null,
>   photographer_id?: number | null,
>   avg_color?: string | null,
>   src?: {
>     original?: string | null,
>     large2x?: string | null,
>     large?: string | null,
>     medium?: string | null,
>     small?: string | null,
>     landscape?: string | null,
>     portrait?: string | null,
>     tiny?: string | null
>   } | null,
>   liked?: boolean | null,
>   alt?: string | null,
>   image?: string | null,
>   duration?: number | null,
>   full_res?: any | null,
>   tags?: string[] | null,
>   video_pictures?: {
>     id?: number | null,
>     nr?: number | null,
>     picture?: string | null
>   }[] | null,
>   user?: {
>     id?: number | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   video_files?: {
>     id?: number | null,
>     quality?: string | null,
>     file_type?: string | null,
>     width?: number | null,
>     height?: number | null,
>     link?: string | null
>   }[] | null,
>   type?: string | null
> }[]
> ```

***

## Photos

### curated

`photos.curated`

List the curated photo feed

**Risk:** `read`

```ts theme={null}
await corsair.pexels.api.photos.curated({ per_page: 25 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `page` | `number` | No | Page number |
| `per_page` | `number` | No | Results per page, at most 80 |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `photos` | `object[]` | Yes | Curated photos on this page |
| `page` | `number \| null` | No | Page returned |
| `per_page` | `number \| null` | No | Results per page |
| `total_results` | `number \| null` | No | Total curated photos |
| `next_page` | `string \| null` | No | URL of the next page |
| `prev_page` | `string \| null` | No | URL of the previous page |

> [accordion] photos full type
>
> ```ts theme={null}
> {
>   id?: number | null,
>   width?: number | null,
>   height?: number | null,
>   url?: string | null,
>   photographer?: string | null,
>   photographer_url?: string | null,
>   photographer_id?: number | null,
>   avg_color?: string | null,
>   src?: {
>     original?: string | null,
>     large2x?: string | null,
>     large?: string | null,
>     medium?: string | null,
>     small?: string | null,
>     landscape?: string | null,
>     portrait?: string | null,
>     tiny?: string | null
>   } | null,
>   liked?: boolean | null,
>   alt?: string | null
> }[]
> ```

***

### get

`photos.get`

Read one photo by id with its rendition URLs

**Risk:** `read`

```ts theme={null}
await corsair.pexels.api.photos.get({ photoId: 2014422 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `photoId` | `number` | Yes | Photo id |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `number \| null` | No | Photo id |
| `width` | `number \| null` | No | Width in pixels |
| `height` | `number \| null` | No | Height in pixels |
| `url` | `string \| null` | No | Photo page URL on Pexels |
| `photographer` | `string \| null` | No | Photographer name |
| `photographer_url` | `string \| null` | No | Photographer profile URL |
| `photographer_id` | `number \| null` | No | Photographer id |
| `avg_color` | `string \| null` | No | Average colour, e.g. #374824 |
| `src` | `object \| null` | No | Rendition URLs |
| `liked` | `boolean \| null` | No | Whether the API key has liked the photo |
| `alt` | `string \| null` | No | Alt text |

> [accordion] src full type
>
> ```ts theme={null}
> {
>   original?: string | null,
>   large2x?: string | null,
>   large?: string | null,
>   medium?: string | null,
>   small?: string | null,
>   landscape?: string | null,
>   portrait?: string | null,
>   tiny?: string | null
> } | null
> ```

***

### search

`photos.search`

Search photos by query, orientation, size and color

**Risk:** `read`

```ts theme={null}
await corsair.pexels.api.photos.search({ query: "nature", orientation: "landscape", per_page: 25 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | Yes | Search query |
| `orientation` | `landscape \| portrait \| square` | No | Aspect orientation filter |
| `size` | `large \| medium \| small` | No | Minimum size filter |
| `color` | `string` | No | Dominant color filter: a color name or a hex value |
| `locale` | `string` | No | Search locale, e.g. en-US, de-DE, ja-JP |
| `page` | `number` | No | Page number |
| `per_page` | `number` | No | Results per page, at most 80 |

color takes a color name or a hex value; src carries all rendition URLs, original included. per\_page is capped at 80 results per page across every list endpoint.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `photos` | `object[]` | Yes | Photos on this page |
| `page` | `number \| null` | No | Page returned |
| `per_page` | `number \| null` | No | Results per page |
| `total_results` | `number \| null` | No | Total matching photos |
| `next_page` | `string \| null` | No | URL of the next page |
| `prev_page` | `string \| null` | No | URL of the previous page |

> [accordion] photos full type
>
> ```ts theme={null}
> {
>   id?: number | null,
>   width?: number | null,
>   height?: number | null,
>   url?: string | null,
>   photographer?: string | null,
>   photographer_url?: string | null,
>   photographer_id?: number | null,
>   avg_color?: string | null,
>   src?: {
>     original?: string | null,
>     large2x?: string | null,
>     large?: string | null,
>     medium?: string | null,
>     small?: string | null,
>     landscape?: string | null,
>     portrait?: string | null,
>     tiny?: string | null
>   } | null,
>   liked?: boolean | null,
>   alt?: string | null
> }[]
> ```

***

## Videos

### get

`videos.get`

Read one video by id with its downloadable renditions

**Risk:** `read`

```ts theme={null}
await corsair.pexels.api.videos.get({ videoId: 2499611 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `videoId` | `number` | Yes | Video id |

video\_files lists every downloadable rendition with quality and file type.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `number \| null` | No | Video id |
| `width` | `number \| null` | No | Width in pixels |
| `height` | `number \| null` | No | Height in pixels |
| `url` | `string \| null` | No | Video page URL on Pexels |
| `image` | `string \| null` | No | Poster image URL |
| `duration` | `number \| null` | No | Duration in seconds |
| `full_res` | `any \| null` | No | Full-resolution info, when Pexels has it |
| `tags` | `string[] \| null` | No | Tags |
| `avg_color` | `string \| null` | No | Average colour |
| `video_pictures` | `object[] \| null` | No | Preview pictures |
| `user` | `object \| null` | No | Video creator |
| `video_files` | `object[] \| null` | No | Downloadable renditions |

> [accordion] video\_pictures full type
>
> ```ts theme={null}
> {
>   id?: number | null,
>   nr?: number | null,
>   picture?: string | null
> }[] | null
> ```

> [accordion] user full type
>
> ```ts theme={null}
> {
>   id?: number | null,
>   name?: string | null,
>   url?: string | null
> } | null
> ```

> [accordion] video\_files full type
>
> ```ts theme={null}
> {
>   id?: number | null,
>   quality?: string | null,
>   file_type?: string | null,
>   width?: number | null,
>   height?: number | null,
>   link?: string | null
> }[] | null
> ```

***

### popular

`videos.popular`

List the popular videos, filtered by size and duration

**Risk:** `read`

```ts theme={null}
await corsair.pexels.api.videos.popular({ min_width: 1280, min_duration: 5 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `min_width` | `number` | No | Minimum width in pixels |
| `min_height` | `number` | No | Minimum height in pixels |
| `min_duration` | `number` | No | Minimum duration in seconds |
| `max_duration` | `number` | No | Maximum duration in seconds |
| `page` | `number` | No | Page number |
| `per_page` | `number` | No | Results per page, at most 80 |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `videos` | `object[]` | Yes | Popular videos on this page |
| `page` | `number \| null` | No | Page returned |
| `per_page` | `number \| null` | No | Results per page |
| `total_results` | `number \| null` | No | Total popular videos |
| `next_page` | `string \| null` | No | URL of the next page |
| `prev_page` | `string \| null` | No | URL of the previous page |

> [accordion] videos full type
>
> ```ts theme={null}
> {
>   id?: number | null,
>   width?: number | null,
>   height?: number | null,
>   url?: string | null,
>   image?: string | null,
>   duration?: number | null,
>   full_res?: any | null,
>   tags?: string[] | null,
>   avg_color?: string | null,
>   video_pictures?: {
>     id?: number | null,
>     nr?: number | null,
>     picture?: string | null
>   }[] | null,
>   user?: {
>     id?: number | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   video_files?: {
>     id?: number | null,
>     quality?: string | null,
>     file_type?: string | null,
>     width?: number | null,
>     height?: number | null,
>     link?: string | null
>   }[] | null
> }[]
> ```

***

### search

`videos.search`

Search videos by query and orientation

**Risk:** `read`

```ts theme={null}
await corsair.pexels.api.videos.search({ query: "waves", orientation: "portrait" });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | Yes | Search query |
| `orientation` | `landscape \| portrait \| square` | No | Aspect orientation filter |
| `size` | `large \| medium \| small` | No | Minimum size: large 4K, medium full HD, small HD |
| `locale` | `string` | No | Search locale, e.g. en-US, de-DE, ja-JP |
| `page` | `number` | No | Page number |
| `per_page` | `number` | No | Results per page, at most 80 |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `videos` | `object[]` | Yes | Videos on this page |
| `page` | `number \| null` | No | Page returned |
| `per_page` | `number \| null` | No | Results per page |
| `total_results` | `number \| null` | No | Total matching videos |
| `next_page` | `string \| null` | No | URL of the next page |
| `prev_page` | `string \| null` | No | URL of the previous page |

> [accordion] videos full type
>
> ```ts theme={null}
> {
>   id?: number | null,
>   width?: number | null,
>   height?: number | null,
>   url?: string | null,
>   image?: string | null,
>   duration?: number | null,
>   full_res?: any | null,
>   tags?: string[] | null,
>   avg_color?: string | null,
>   video_pictures?: {
>     id?: number | null,
>     nr?: number | null,
>     picture?: string | null
>   }[] | null,
>   user?: {
>     id?: number | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   video_files?: {
>     id?: number | null,
>     quality?: string | null,
>     file_type?: string | null,
>     width?: number | null,
>     height?: number | null,
>     link?: string | null
>   }[] | null
> }[]
> ```

***


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