Add Category to Clip

Adds a category to an existing clip.

Endpoint

POST /api/app/clips/{clipId}/categories/

Parameters

Path Parameters

Parameter	Type	Required	Description
clipId	string	Yes	The unique identifier of the clip

Request Body

Parameter	Type	Required	Description
id	string	Yes	The GUID of the category to add

Authentication

This endpoint requires authentication using your API key. See Authentication for details.

Request

Headers

x-storyteller-api-key: your-api-key-here
Content-Type: application/json

Example Request

POST /api/app/clips/12345678-1234-1234-1234-123456789abc/categories/
Host: api.storyteller.example.com
x-storyteller-api-key: your-api-key-here
Content-Type: application/json

{
  "id": "87654321-4321-4321-4321-cba987654321"
}

Response

Success Response

Status Code: 200 OK

{
  "success": true,
  "message": "Category successfully added to clip"
}

Error Responses

Status Code: 400 Bad Request

{
  "error": "BadRequest",
  "message": "Invalid clip ID or category ID"
}

Status Code: `401 Unauthorized**

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

Status Code: `404 Not Found**

{
  "error": "NotFound",
  "message": "Clip or category not found"
}

Status Code: `409 Conflict**

{
  "error": "Conflict",
  "message": "Category is already associated with this clip"
}

Code Examples

JavaScriptPythonC#cURL

const response = await fetch(
  'https://api.storyteller.example.com/api/app/clips/12345678-1234-1234-1234-123456789abc/categories/',
  {
    method: 'POST',
    headers: {
      'x-storyteller-api-key': 'your-api-key-here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      id: '87654321-4321-4321-4321-cba987654321'
    })
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://api.storyteller.example.com/api/app/clips/12345678-1234-1234-1234-123456789abc/categories/"
headers = {
    "x-storyteller-api-key": "your-api-key-here",
    "Content-Type": "application/json"
}
data = {
    "id": "87654321-4321-4321-4321-cba987654321"
}

response = requests.post(url, headers=headers, json=data)
data = response.json()
print(data)

using HttpClient client = new HttpClient();

client.DefaultRequestHeaders.Add("x-storyteller-api-key", "your-api-key-here");

var requestBody = new { id = "87654321-4321-4321-4321-cba987654321" };
var json = System.Text.Json.JsonSerializer.Serialize(requestBody);

var response = await client.PostAsync(
    "https://api.storyteller.example.com/api/app/clips/12345678-1234-1234-1234-123456789abc/categories/",
    new StringContent(json, System.Text.Encoding.UTF8, "application/json")
);

var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);

curl -X POST \
  -H "x-storyteller-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"id": "87654321-4321-4321-4321-cba987654321"}' \
  "https://api.storyteller.example.com/api/app/clips/12345678-1234-1234-1234-123456789abc/categories/"

Notes

• Categories must exist before they can be added to clips
• A clip can have multiple categories
• Adding the same category twice will result in a 409 Conflict error
• This operation is idempotent - calling it multiple times with the same parameters will not cause issues beyond the conflict error