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

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

Code Examples

List videos with filters

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

Semantic search

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

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"

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

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.

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