# Fetch API

Expand endpoint spec below to see parameters and a sample response.

These API endpoints require an API Key. Your organization's API Key can be found in [Settings -> Developer](https://admin.capsule.video/#/settings/developer/) in your Capsule dashboard.

{% hint style="info" %}
Capsule API Keys should be treated as application secrets and not used client-side, since they can be used to fetch user data.
{% endhint %}

### Fetch multiple videos

## Returns an array of videos, with various filters & pagination

<mark style="color:blue;">`GET`</mark> `GET https://api.capsule.video/videos`

Expand this section for parameters and example response.

#### Query Parameters

| Name                                   | Type    | Description                                                                                                             |
| -------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| slug<mark style="color:red;">\*</mark> | String  | Capsule slug. The subdomain part of your capsule.video URL (e.g. "your-capsule" in **your-capsule-slug**.capsule.video) |
| email                                  | String  | Filter by email address of the person who submitted the video                                                           |
| count                                  | Integer | Page size, default is 25                                                                                                |
| page                                   | Integer | Page number                                                                                                             |
| sort                                   |         | Can be set to 'asc' or 'desc', descending is the default                                                                |
| category                               | String  | Filter by category slug                                                                                                 |

#### Headers

| Name                                            | Type   | Description                                      |
| ----------------------------------------------- | ------ | ------------------------------------------------ |
| Authorization<mark style="color:red;">\*</mark> | String | Header value is "Bearer \<your-capsule-api-key>" |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
   "videos": [
      {
         "captions" : [
            {
               "language" : "en",
               "url" : "https://url.to/transcript.vtt"
            }
         ],
         "createdAt" : "2021-07-020T19:00:00Z",
         "download" : "https://url.to/download.mp4",
         "email" : "john@test.com",
         "id" : "G5Rs47hK39dg",
         "metadata" : {
            "category" : "e1234-category-1",
            "data1" : "Name",
            "question" : "Question?"
         },
         "thumbnail" : "https://url.to/thumb.jpg",
         "thumbnailStrip" : "https://url.to/strip.jpg",
         "video" : "https://url.to/play.mp4"
      }
   ]
}
```

{% endtab %}
{% endtabs %}

### Fetch a single video

## Returns the details for a single video

<mark style="color:blue;">`GET`</mark> `https://api.capsule.video/videos/<video_id>`

Expand this section for parameters and example response.

#### Path Parameters

| Name                                        | Type   | Description                                                                                                                                                                           |
| ------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| video\_id<mark style="color:red;">\*</mark> | String | The ID of the video. This is the unique ID at the end of the URL when viewing a video in a public-facing Capsule. It's also the ID sent via [webhook](/accessing-videos/webhooks.md). |

#### Query Parameters

| Name                                   | Type   | Description                                                                                                                                             |
| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| slug<mark style="color:red;">\*</mark> | String | Slug for the Capsule that contains the video. The subdomain part of your capsule.video URL (e.g. "your-capsule" in **your-capsule-slug**.capsule.video) |

#### Headers

| Name                                            | Type   | Description                                      |
| ----------------------------------------------- | ------ | ------------------------------------------------ |
| Authorization<mark style="color:red;">\*</mark> | String | Header value is "Bearer \<your-capsule-api-key>" |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "captions" : [
       {
          "language" : "en",
          "url" : "https://url.to/transcript.vtt"
       }
    ],
    "createdAt" : "2021-07-020T19:00:00Z",
    "download" : "https://url.to/download.mp4",
    "email" : "john@test.com",
    "id" : "G5Rs47hK39dg",
    "metadata" : {
       "category" : "e1234-category-1",
       "data1" : "Name",
       "question" : "Question?"
    },
    "thumbnail" : "https://url.to/thumb.jpg",
    "thumbnailStrip" : "https://url.to/strip.jpg",
    "video" : "https://url.to/play.mp4"
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.capsule.video/accessing-videos/fetch-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.