API v1

DanSUGC B-Roll API

Search, preview, and purchase high-quality B-roll video clips programmatically. Perfect for integrating UGC content into your platform.

Quick Start

1. Get your API key

Create an API key in your dashboard. Keys are dsk_ prefixed with configurable scopes.

2. Make your first request

curl -H "Authorization: Bearer dsk_your_key" \
  https://dansugc.com/api/v1/broll

3. Browse the docs

Visit /docs for the interactive OpenAPI explorer, or read on for detailed guides.

Authentication

All requests must include a Bearer token in the Authorization header. Keys are prefixed with dsk_ and are tied to a specific source and set of permission scopes.

Example header

Authorization: Bearer dsk_abc123...

Rate Limits

Default: 60 requests/minute. When exceeded, you'll receive a 429 response with Retry-After and X-RateLimit-Limit headers.

Error Codes

401 — Invalid or missing key

403 — Insufficient scopes

429 — Rate limit exceeded

Scopes

broll:read — Browse & search

broll:purchase — Buy videos

broll:billing — View purchases

keys:manage — Manage customer keys

Endpoints

Method	Endpoint	Scope	Description
GET	/api/v1/broll	`broll:read`	List & search B-roll videos
GET	/api/v1/broll/:id	`broll:read`	Get single video details
POST	/api/v1/broll/purchase	`broll:purchase`	Purchase videos (returns download URLs)
GET	/api/v1/broll/purchases	`broll:billing`	List purchases for billing
GET	/api/v1/broll/filters	`broll:read`	Get all unique filter values
POST	/api/v1/keys	`keys:manage`	Create customer API key
GET	/api/v1/keys	`keys:manage`	List customer keys
DELETE	/api/v1/keys?id=:id	`keys:manage`	Revoke customer key

Code Examples

List videos with filters

curl -H "Authorization: Bearer dsk_your_key" \
  "https://dansugc.com/api/v1/broll?emotion=happy&gender=female&media_type=video&limit=10"

Semantic search

curl -H "Authorization: Bearer dsk_your_key" \
  "https://dansugc.com/api/v1/broll?semantic_search=happy+woman+indoor"

Paginate through results

curl -H "Authorization: Bearer dsk_your_key" \
  "https://dansugc.com/api/v1/broll?page=2&limit=50&sort_by=virality_score&sort_order=desc"

Purchase videos

curl -X POST \
  -H "Authorization: Bearer dsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"video_ids": ["uuid-1", "uuid-2"]}' \
  "https://dansugc.com/api/v1/broll/purchase"

Get billing summary

curl -H "Authorization: Bearer dsk_your_key" \
  "https://dansugc.com/api/v1/broll/purchases?start_date=2026-01-01&end_date=2026-01-31"

Search purchases by keyword

curl -H "Authorization: Bearer dsk_your_key" \
  "https://dansugc.com/api/v1/broll/purchases?search=happy+reaction&start_date=2026-01-01"

Semantic search purchases

curl -H "Authorization: Bearer dsk_your_key" \
  "https://dansugc.com/api/v1/broll/purchases?semantic_search=woman+laughing+outdoors&emotion=happy"

Pagination

All list endpoints use page-based pagination. Control results with page and limit query parameters.

Parameters

page — Page number (default: 1)

limit — Results per page (default: 24, max: 100 for /broll, 500 for /broll/purchases)

sort_by — Sort field (created_at, virality_score, download_count, difficulty_level)

sort_order — asc or desc (default: desc)

Response

pagination.page — Current page

pagination.limit — Items per page

pagination.total_pages — Total pages available

pagination.has_more — Whether more pages exist

total — Total matching results

Example: iterate through all pages

let page = 1;
let hasMore = true;
while (hasMore) {
  const res = await fetch(
    `${BASE_URL}/broll?page=${page}&limit=100`,
    { headers }
  );
  const data = await res.json();
  // Process data.videos...
  hasMore = data.pagination.has_more;
  page++;
}

Semantic Search

Use the semantic_search query parameter to find videos by meaning rather than keywords. This uses AI embeddings to match your natural-language description against our video library.

How it works

1. Your query is converted into a 768-dimensional embedding

2. We find videos with the most similar embeddings (cosine similarity)

3. Results are ranked by relevance score

4. Other filters (emotion, gender, etc.) are applied on top

Example queries

happy woman indoor

excited reaction to gift

person walking in city

cooking in modern kitchen

Note: You cannot combine search (text search) and semantic_search in the same request. The API will return a 400 error if both are provided.

MCP Integration

Connect AI assistants like Claude directly to the DanSUGC B-roll library using the Model Context Protocol (MCP). Your AI assistant can search, browse, and purchase videos on your behalf.

Endpoint

https://dansugc.com/api/mcp

Stateless Streamable HTTP transport. Uses the same dsk_ API key authentication as the REST API.

Available Tools

search_videos — Search & browse B-roll

get_video — Get video details by ID

purchase_videos — Buy videos with credits

list_purchases — View purchase history

get_balance — Check account summary

manage_customer_keys — Create/list/revoke keys

Add this to your claude_desktop_config.json:

claude_desktop_config.json

{
  "mcpServers": {
    "dansugc": {
      "url": "https://dansugc.com/api/mcp",
      "headers": {
        "Authorization": "Bearer dsk_your_key"
      }
    }
  }
}

Example Prompts

"Find me 5 happy female B-roll clips filmed indoors"

"Search for videos of someone cooking in a modern kitchen"

"Purchase these 3 videos: [paste IDs]"

"Show me my purchase history for January 2026"

"What's my current account balance?"

Billing

Purchases are tracked per API key and reconciled monthly. Use the billing endpoint to generate reports for any date range.

How purchases work

1. Call POST /broll/purchase with video IDs

2. Full-quality download URLs are returned immediately

3. Each video is priced by its difficulty tier

4. Duplicate purchases are idempotent (return existing URLs)

Monthly reconciliation

1. Call GET /broll/purchases with date range

2. Response includes per-purchase details and period summary

3. Use summary.total_amount for invoice totals

Migration Guide (v0 → v1)

The legacy /api/external/broll endpoints still work but are deprecated. They will be sunset on September 1, 2026. Here's what changed:

Change	Legacy (v0)	v1
Base URL	/api/external/broll	/api/v1/broll
API Key	Single shared secret	`dsk_` prefixed per-tenant key
Source field	Required in request body	Automatic from API key
Rate limiting	None	60 req/min (configurable)
Semantic search	Not available	`semantic_search` param

Deprecation timeline: Legacy endpoints return Deprecation: true and Sunset: 2026-09-01 headers.

Action required: Update your base URL from /api/external/broll to /api/v1/broll, switch to a dsk_ key, and remove the source field from purchase requests.

Building a platform with multiple customers? Read the Platform Integration Guide.

Interactive API explorer available at /docs. OpenAPI spec at /api/openapi.json.