{"openapi":"3.0.3","info":{"title":"Brollvia API","version":"1.8.1","description":"Stock footage, photos, music and SFX for filmmakers \u2014 searchable and licensable programmatically. Every download writes a licence record. Authenticate with an API key from Settings \u2192 Developer, or with an OAuth 2.1 access token (discovery: /.well-known/oauth-authorization-server, dynamic registration: /oauth/register). The same credentials also unlock the MCP server at /mcp."},"servers":[{"url":"https://brollvia.com/api/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from Settings \u2192 Developer, or an OAuth 2.1 access token. Scopes: read, download, collections:write."},"oauth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://brollvia.com/oauth/authorize","tokenUrl":"https://brollvia.com/oauth/token","refreshUrl":"https://brollvia.com/oauth/token","scopes":{"read":"Search and read the library","download":"Download media and create licence records","collections:write":"Create and edit shot lists"}}}}},"schemas":{"Asset":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"slug":{"type":"string"},"type":{"type":"string","enum":["photo","video","audio"]},"tier":{"type":"string","enum":["free","pro"]},"preview_url":{"type":"string","nullable":true},"url":{"type":"string"},"licence":{"type":"string"}}},"Collection":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"slug":{"type":"string"},"asset_count":{"type":"integer"}}}}},"paths":{"/search":{"get":{"summary":"Search the library (natural language is parsed into filters)","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}},"parameters":[{"name":"q","in":"query","description":"Keywords or a described shot, e.g. \"rainy tokyo alley at night, drone\"","schema":{"type":"string"}},{"name":"type","in":"query","description":"photo | video | audio","schema":{"type":"string"}},{"name":"tier","in":"query","description":"free | pro","schema":{"type":"string"}},{"name":"shot_type","in":"query","description":"","schema":{"type":"string"}},{"name":"camera_movement","in":"query","description":"","schema":{"type":"string"}},{"name":"time_of_day","in":"query","description":"","schema":{"type":"string"}},{"name":"orientation","in":"query","description":"","schema":{"type":"string"}},{"name":"resolution","in":"query","description":"hd | 4k","schema":{"type":"string"}},{"name":"color","in":"query","description":"Hex fragment, e.g. 2DD4BF","schema":{"type":"string"}},{"name":"sort","in":"query","description":"relevance | newest | downloads | views | curated","schema":{"type":"string"}},{"name":"per_page","in":"query","description":"","schema":{"type":"integer"}},{"name":"cursor","in":"query","description":"From meta.next_cursor","schema":{"type":"string"}}]}},"/assets/curated":{"get":{"summary":"Editor-curated assets","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}}}},"/assets/trending":{"get":{"summary":"Most-downloaded assets","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}}}},"/assets/{id}":{"get":{"summary":"Full asset metadata","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/assets/{id}/similar":{"get":{"summary":"Similar assets (v1.5 similarity engine: embeddings when configured, blended with palette, perceptual hash and tags)","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/assets/visual-search":{"post":{"summary":"Search by image URL (fetched server-side with SSRF guards; the image is never stored)","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image_url":{"type":"string","description":"Public https URL of a jpg/png/webp still"}},"required":["image_url"]}}}}}},"/assets/{id}/download":{"post":{"summary":"Licence-checked download \u2014 returns a signed URL (15 min) and the licence record","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"variant":{"type":"string","enum":["original","hd"],"default":"original"}}}}}}}},"/script/suggest":{"post":{"summary":"Script-to-B-roll: turn script lines into shot suggestions. Body: {script, per_beat?, save_as?} \u2014 save_as also saves the top pick per beat as a collection (needs collections:write)","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["script"],"properties":{"script":{"type":"string"},"per_beat":{"type":"integer","minimum":1,"maximum":6},"save_as":{"type":"string"}}}}}}}},"/licences/{id}":{"get":{"summary":"Licence certificate data for one of your downloads (add ?format=pdf for the PDF)","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/collections":{"get":{"summary":"Your collections (add ?public=1 for public ones)","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}}},"post":{"summary":"Create a collection / shot list","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"description":{"type":"string"},"is_public":{"type":"boolean"}}}}}}}},"/collections/{id}":{"get":{"summary":"One collection with its assets","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}}}},"/collections/{id}/assets":{"post":{"summary":"Add an asset to a collection","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["asset_id"],"properties":{"asset_id":{"type":"integer"}}}}}}}},"/collections/{id}/assets/{asset_id}":{"delete":{"summary":"Remove an asset from a collection","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}}}},"/topics":{"get":{"summary":"Topics and categories","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}}}},"/contributors/{id}":{"get":{"summary":"Contributor profile and stats","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}}}},"/me":{"get":{"summary":"The account and plan behind the key","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}}}},"/me/usage":{"get":{"summary":"Usage counters and plan limits for this key","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"403":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"404":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"},"429":{"description":"Error envelope: { \"error\": { \"code\": \"\u2026\", \"message\": \"\u2026\" } }"}}}}}}