> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.reka.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.reka.ai/_mcp/server.

# Video Group Management

> Organize videos into named collections and manage group metadata

> **Info**
>
> For chat over text, images and short videos, use the OpenAI-compatible [Chat Completions API](/chat/overview).

Video groups cluster related uploads, for example by end customer, internal application or industry vertical, so you can scope search and listings to one group.

## Create a video group

`POST /v2/video-groups`

#### Bash

```bash
curl -X POST https://vision-agent.api.reka.ai/v2/video-groups \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Launch Clips",
    "metadata": {
      "campaign": "launch-2024",
      "priority": "high"
    }
  }'
```

#### Python

```python
import requests

BASE_URL = "https://vision-agent.api.reka.ai"
headers = {"X-Api-Key": REKA_API_KEY}

payload = {
    "name": "Product Launch Clips",
    "metadata": {"campaign": "launch-2024", "priority": "high"},
}
response = requests.post(f"{BASE_URL}/v2/video-groups", json=payload, headers=headers)
response.raise_for_status()
group = response.json()
```

### Parameters

* **`name`** (required): Display name for the group.
* **`metadata`** (optional): Free-form JSON object for tags or integration IDs.

### Response

```json
{
  "group_id": "20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37",
  "name": "Product Launch Clips",
  "metadata": {
    "campaign": "launch-2024",
    "priority": "high"
  },
  "created_at": "2024-11-04T01:04:33.123456+00:00",
  "updated_at": "2024-11-04T01:04:33.123456+00:00"
}
```

## Get a video group

`GET /v2/video-groups/{group_id}`

#### Bash

```bash
curl https://vision-agent.api.reka.ai/v2/video-groups/20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37 \
  -H "X-Api-Key: YOUR_API_KEY"
```

#### Python

```python
group_id = "20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37"
response = requests.get(f"{BASE_URL}/v2/video-groups/{group_id}", headers=headers)
response.raise_for_status()
group = response.json()
```

The response has the same shape as the create response.

## List video groups

`GET /v2/video-groups`

#### Bash

```bash
curl https://vision-agent.api.reka.ai/v2/video-groups \
  -H "X-Api-Key: YOUR_API_KEY"
```

#### Python

```python
response = requests.get(f"{BASE_URL}/v2/video-groups", headers=headers)
response.raise_for_status()
groups = response.json()["results"]
```

### Response

```json
{
  "results": [
    {
      "group_id": "20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37",
      "name": "Product Launch Clips",
      "metadata": {
        "campaign": "launch-2024",
        "priority": "medium"
      },
      "created_at": "2024-11-04T01:04:33.123456+00:00",
      "updated_at": "2024-11-05T03:28:09.000123+00:00"
    }
  ]
}
```

## Update a video group

`PATCH /v2/video-groups/{group_id}` changes the group's name, metadata, or both.

#### Bash

```bash
curl -X PATCH https://vision-agent.api.reka.ai/v2/video-groups/20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Launch Clips (Q4)",
    "metadata": {
      "campaign": "launch-2024",
      "priority": "medium"
    }
  }'
```

#### Python

```python
payload = {
    "name": "Product Launch Clips (Q4)",
    "metadata": {"campaign": "launch-2024", "priority": "medium"},
}
response = requests.patch(f"{BASE_URL}/v2/video-groups/{group_id}", json=payload, headers=headers)
response.raise_for_status()
print(response.json())
```

### Parameters

* **`name`** (optional): New display name.
* **`metadata`** (optional): Replacement metadata object. Send the full object you want stored.

The response is the updated group.

## Delete a video group

`DELETE /v2/video-groups/{group_id}`

#### Bash

```bash
curl -X DELETE https://vision-agent.api.reka.ai/v2/video-groups/20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37 \
  -H "X-Api-Key: YOUR_API_KEY"
```

#### Python

```python
response = requests.delete(f"{BASE_URL}/v2/video-groups/{group_id}", headers=headers)
response.raise_for_status()
print(response.json())
```

### Response

```json
{
  "status": "success",
  "message": "Video group deleted successfully"
}
```

## List videos in a group

`GET /v2/video-groups/{group_id}/videos` lists the videos in one group. Pass `default` as the `group_id` to list videos that are not in any custom group.

#### Bash

```bash
curl https://vision-agent.api.reka.ai/v2/video-groups/20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37/videos \
  -H "X-Api-Key: YOUR_API_KEY"
```

#### Python

```python
response = requests.get(f"{BASE_URL}/v2/video-groups/{group_id}/videos", headers=headers)
response.raise_for_status()
videos = response.json()["results"]
```

The response is a `results` array of videos, the same shape that [List Videos](/vision/video-management#list-videos) returns.

## Move videos to a group

`POST /v2/video-groups/{group_id}/videos` moves existing videos into the destination group. To move a single video you can also [update the video](/vision/video-management#update-a-video) with a new `group_id`.

#### Bash

```bash
curl -X POST https://vision-agent.api.reka.ai/v2/video-groups/20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37/videos \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "2ee0262d-1dc5-4a50-adb3-e40da8893c8d"
    ]
  }'
```

#### Python

```python
payload = {
    "video_ids": [
        "550e8400-e29b-41d4-a716-446655440000",
        "2ee0262d-1dc5-4a50-adb3-e40da8893c8d",
    ]
}
response = requests.post(f"{BASE_URL}/v2/video-groups/{group_id}/videos", json=payload, headers=headers)
response.raise_for_status()
print(response.json())
```

### Response

```json
{
  "status": "success",
  "moved_count": 2,
  "group_id": "20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37",
  "video_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "2ee0262d-1dc5-4a50-adb3-e40da8893c8d"
  ]
}
```