Vision

Video Group Management

Video groups let you cluster related uploads—for example, by end-customer, internal application, or industry vertical—so you can scope video search results to just the assets that matter for a given workflow.

Create Video Groups

Endpoint

  • POST /videos/groups

Request

Bash

$curl -X POST https://vision-agent.api.reka.ai/videos/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

1import requests
2
3BASE_URL = "https://vision-agent.api.reka.ai"
4payload = {
5    "name": "Product Launch Clips",
6    "metadata": {"campaign": "launch-2024", "priority": "high"},
7}
8headers = {"X-Api-Key": REKA_API_KEY}
9response = requests.post(f"{BASE_URL}/videos/groups", json=payload, headers=headers)
10response.raise_for_status()
11print(response.json())

Parameters

  • name (required): Display name for the new group.
  • metadata (optional): Free-form JSON object (≤500 characters) for attaching tags or integration IDs.

Response

Standard accounts can create up to 10 custom video groups. The API returns the newly created group:

1{
2  "group_id": "20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37",
3  "name": "Product Launch Clips",
4  "metadata": {
5    "campaign": "launch-2024",
6    "priority": "high"
7  },
8  "created_at": "2024-11-04T01:04:33.123456+00:00",
9  "updated_at": "2024-11-04T01:04:33.123456+00:00"
10}

Retrieve a Video Group

Endpoint

  • GET /videos/groups/{group_id}

Request

Bash

$curl -X GET https://vision-agent.api.reka.ai/videos/groups/{GROUP_ID} \
>  -H "X-Api-Key: YOUR_API_KEY"

Python

1response = requests.get(
2    f"{BASE_URL}/videos/groups/{group_id}",
3    headers={"X-Api-Key": REKA_API_KEY},
4)
5response.raise_for_status()
6group = response.json()

Response

The response mirrors the VideoGroupResponse schema shown above.

Update a Video Group

Endpoint

  • PATCH /videos/groups/{group_id}

Request

Bash

$curl -X PATCH https://vision-agent.api.reka.ai/videos/groups/{GROUP_ID} \
>  -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

1payload = {
2    "name": "Product Launch Clips (Q4)",
3    "metadata": {"campaign": "launch-2024", "priority": "medium"},
4}
5response = requests.patch(
6    f"{BASE_URL}/videos/groups/{group_id}",
7    json=payload,
8    headers={"X-Api-Key": REKA_API_KEY},
9)
10response.raise_for_status()
11print(response.json())

Parameters

  • name (optional): New display name (cannot be blank). Provide at least one non-empty field in the request.
  • metadata (optional): Replaces the stored metadata JSON. Send the full object you want saved (must contain at least one key if included).

You must update at least one of these fields per request—sending both name and metadata empty results in a validation error.

Response

Returns the updated group.

Delete a Video Group

Endpoint

  • DELETE /videos/groups/{group_id}

Request

Bash

$curl -X DELETE https://vision-agent.api.reka.ai/videos/groups/{GROUP_ID} \
>  -H "X-Api-Key: YOUR_API_KEY"

Python

1response = requests.delete(
2    f"{BASE_URL}/videos/groups/{group_id}",
3    headers={"X-Api-Key": REKA_API_KEY},
4)
5response.raise_for_status()
6print(response.json())  # {"status": "success"}

Response

1{"status": "success"}

Delete all videos associated with the group before removing it; group deletion is rejected while videos still reference it.

List Video Groups

Endpoint

  • GET /videos/groups

Request

Bash

$curl -X GET https://vision-agent.api.reka.ai/videos/groups \
>  -H "X-Api-Key: YOUR_API_KEY"

Python

1response = requests.get(
2    f"{BASE_URL}/videos/groups",
3    headers={"X-Api-Key": REKA_API_KEY},
4)
5response.raise_for_status()
6groups = response.json()["results"]

Response

Returns:

1{
2  "results": [
3    {
4      "group_id": "20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37",
5      "name": "Product Launch Clips",
6      "metadata": {
7        "campaign": "launch-2024",
8        "priority": "medium"
9      },
10      "created_at": "2024-11-04T01:04:33.123456+00:00",
11      "updated_at": "2024-11-05T03:28:09.000123+00:00"
12    }
13  ]
14}

List Videos in a Group

Use this endpoint to scope Vision responses to a specific collection.

Endpoint

  • GET /videos/groups/{group_id}/videos
    • Pass group_id=default to fetch videos that have never been assigned to a custom group.

Request

Bash

$curl -X GET https://vision-agent.api.reka.ai/videos/groups/{GROUP_ID}/videos \
>  -H "X-Api-Key: YOUR_API_KEY"

Python

1response = requests.get(
2    f"{BASE_URL}/videos/groups/{group_id}/videos",
3    headers={"X-Api-Key": REKA_API_KEY},
4)
5response.raise_for_status()
6videos = response.json()["results"]

Response

Returns the same VideosGetResponse payload that /videos/get provides, including each video’s video_id, signed URL, metadata, indexing state, and effective group_id. Videos inherited from the default pool appear with "group_id": "default" in the response.

Example response:

1{
2  "results": [
3    {
4      "video_id": "2ee0262d-1dc5-4a50-adb3-e40da8893c8d",
5      "url": "https://cdn.reka.ai/videos/2ee0262d-1dc5-4a50-adb3-e40da8893c8d?signature=...",
6      "metadata": {
7        "video_name": "Retail Store Cameras – November",
8        "title": "Retail Store Cameras – November",
9        "duration": 3600.12,
10        "thumbnail": "https://cdn.reka.ai/thumbnails/2ee0262d.jpg"
11      },
12      "indexing_status": "indexed",
13      "indexing_type": "fast_search",
14      "group_id": "8d6f6d03-f764-4dd2-a416-379040ce5d09"
15    },
16    {
17      "video_id": "73bca1c4-e1e2-4c2b-bd7f-682696c072db",
18      "url": "https://cdn.reka.ai/videos/73bca1c4-e1e2-4c2b-bd7f-682696c072db?signature=...",
19      "metadata": {
20        "video_name": "Manufacturing Line QA",
21        "title": "Manufacturing Line QA",
22        "duration": 965.23,
23        "thumbnail": "https://cdn.reka.ai/thumbnails/73bca1c4.jpg"
24      },
25      "indexing_status": "indexed",
26      "indexing_type": "fast_search",
27      "group_id": "8d6f6d03-f764-4dd2-a416-379040ce5d09"
28    },
29    {
30      "video_id": "32041730-c45c-4efc-a668-b252f3b78f59",
31      "url": "https://cdn.reka.ai/videos/32041730-c45c-4efc-a668-b252f3b78f59?signature=...",
32      "metadata": {
33        "video_name": "Support Call Recording",
34        "title": "Support Call Recording",
35        "duration": 185.5,
36        "thumbnail": "https://cdn.reka.ai/thumbnails/32041730.jpg"
37      },
38      "indexing_status": "indexed",
39      "indexing_type": "reels",
40      "group_id": "8d6f6d03-f764-4dd2-a416-379040ce5d09"
41    }
42  ]
43}