{"openapi":"3.1.0","info":{"title":"Verified Footage API","description":"Search a library of real, human-captured, location-tagged footage with provenance — built for AI to ground on, cite, and reuse. Every clip is uploaded by a verified account and screened to be genuine (never AI-generated; no edited clips/screen recordings/stock). Each result carries a classification level (verified | signed | certified). Returns rich metadata, an embeddable player, and a download URL. Authenticate with an API key: header `Authorization: Bearer vf_...` (get one at https://www.verifiedfootage.com/connect). Free to use; attribution appreciated.","version":"2.0.0"},"servers":[{"url":"https://www.verifiedfootage.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"vf_<token>"}}},"paths":{"/api/search":{"get":{"operationId":"searchFootage","summary":"Search footage (query string)","description":"Returns clips ranked by relevance. Every param is optional; with none it browses the newest clips. For programmatic use, POST with a JSON body is usually cleaner.","parameters":[{"name":"query","in":"query","required":false,"description":"Natural-language description of the footage (semantic ranking).","schema":{"type":"string","description":"Natural-language description of the footage (semantic ranking)."}},{"name":"location","in":"query","required":false,"description":"A place — landmark, neighborhood, or city, e.g. \"Brooklyn Bridge\". Smart-resolved to a search radius; finds nearby clips regardless of how each was tagged.","schema":{"type":"string","description":"A place — landmark, neighborhood, or city, e.g. \"Brooklyn Bridge\". Smart-resolved to a search radius; finds nearby clips regardless of how each was tagged."}},{"name":"radius_km","in":"query","required":false,"description":"Radius in km around `location`.","schema":{"type":"number","default":2,"description":"Radius in km around `location`."}},{"name":"contributor","in":"query","required":false,"description":"Only footage from this contributor, by @handle (public profiles only), e.g. \"@sofi\".","schema":{"type":"string","description":"Only footage from this contributor, by @handle (public profiles only), e.g. \"@sofi\"."}},{"name":"classification","in":"query","required":false,"description":"Verification level(s) to require.","schema":{"type":"string","description":"Comma-separated, or repeat the param."}},{"name":"no_people","in":"query","required":false,"description":"True to exclude clips containing people.","schema":{"type":"boolean","description":"True to exclude clips containing people."}},{"name":"orientation","in":"query","required":false,"schema":{"type":"string","enum":["horizontal","vertical"]}},{"name":"min_resolution","in":"query","required":false,"description":"\"1080p\" | \"4k\" | a pixel height.","schema":{"type":"string","description":"\"1080p\" | \"4k\" | a pixel height."}},{"name":"shot_type","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated, or repeat the param."}},{"name":"season","in":"query","required":false,"schema":{"type":"string","enum":["winter","spring","summer","autumn"]}},{"name":"weather","in":"query","required":false,"description":"e.g. [\"snow\",\"rain\",\"clear\",\"overcast\",\"fog\"].","schema":{"type":"string","description":"Comma-separated, or repeat the param."}},{"name":"time_of_day","in":"query","required":false,"description":"e.g. [\"golden_hour\",\"afternoon\",\"night\"].","schema":{"type":"string","description":"Comma-separated, or repeat the param."}},{"name":"country","in":"query","required":false,"description":"e.g. \"Japan\".","schema":{"type":"string","description":"e.g. \"Japan\"."}},{"name":"stamp","in":"query","required":false,"description":"A stamp handle (from /api/facets `stamps`). Restricts to clips carrying that verified place/brand stamp, e.g. footage shot inside Madison Square Garden.","schema":{"type":"string","description":"A stamp handle (from /api/facets `stamps`). Restricts to clips carrying that verified place/brand stamp, e.g. footage shot inside Madison Square Garden."}},{"name":"keywords","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated, or repeat the param."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":30,"default":12}}],"responses":{"200":{"description":"Ranked clips.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique clip id."},"title":{"type":"string"},"description":{"type":["string","null"],"description":"AI-generated caption of the footage."},"score":{"type":["number","null"],"description":"Relevance 0–1 when the result was ranked by a query/location."},"location":{"type":"string","description":"Where it was shot, e.g. \"Soho, New York\"."},"place":{"type":["string","null"],"description":"Nearest named place / landmark, e.g. \"Brooklyn Bridge\"."},"neighborhood":{"type":["string","null"],"description":"Neighborhood, e.g. \"DUMBO\"."},"contributor":{"type":["object","null"],"description":"Who shot it: { handle, url } for a public profile, or null when the contributor keeps their profile private."},"coordinates":{"type":["string","null"],"description":"\"protected\" for device-verified tiers (an exact point exists, available under license, never published); null for self-attested."},"captured_at":{"type":["string","null"],"format":"date-time"},"duration_seconds":{"type":["number","null"]},"orientation":{"type":"string","enum":["horizontal","vertical"]},"resolution":{"type":["string","null"],"description":"Source resolution, e.g. \"3840x2160\"."},"aspect_ratio":{"type":["string","null"],"description":"e.g. \"16:9\"."},"season":{"type":["string","null"],"description":"winter | spring | summer | autumn (derived from real capture time)."},"time_of_day":{"type":["string","null"],"description":"e.g. golden_hour | afternoon | night."},"weather":{"type":["object","null"],"description":"Captured weather, e.g. { \"summary\": \"snow\", \"temp_c\": -2 }."},"keywords":{"type":"array","items":{"type":"string"}},"has_people":{"type":["boolean","null"]},"classification":{"type":"string","enum":["verified","signed","certified"],"description":"Assurance level (see /classification, the source of truth). verified = a phone-verified real person uploaded a genuine clip; location self-reported. signed = the original file proves both device and embedded GPS. certified = signed in the device Secure Enclave at capture inside the app — tamper-evident. Parallel levels, not quality grades. (Also returned as \"provenance\" for back-compat.)"},"provenance":{"type":"string","enum":["verified","signed","certified"],"description":"Alias of `classification`."},"ai_generated":{"type":"boolean","description":"Always false — real, human-captured footage."},"verified":{"type":"boolean","description":"True when the clip is processed and available."},"thumbnail_url":{"type":"string","format":"uri"},"embed_url":{"type":"string","format":"uri","description":"Vanity inline player to embed in a UI or chat."},"download_url":{"type":"string","format":"uri","description":"Download the file (routes through the site for attribution)."},"page_url":{"type":"string","format":"uri","description":"Human-viewable verified clip page — link here when citing."},"license":{"type":"string","enum":["commercial","editorial"],"description":"\"editorial\" clips contain a recognizable brand/logo, person, or copyrighted work and are NOT cleared for commercial use — fine for reporting, social, research, and AI training."},"commercial_use_ok":{"type":"boolean"},"editorial_reasons":{"type":["array","null"],"items":{"type":"string"}}}}},"count":{"type":"integer"},"message":{"type":"string","description":"Present only when 0 results — a plain-language reason."},"issues":{"type":"array","items":{"type":"string"},"description":"Present only when 0 results — the specific constraints with nothing to match."},"resolved":{"type":"object","description":"Echo of how the server interpreted the request (query, resolved location, filters)."}}}}}},"401":{"description":"Missing/invalid API key."}}},"post":{"operationId":"searchFootagePost","summary":"Search footage (JSON body)","description":"Same engine as GET, with a structured JSON body. Build a request: a natural-language `query`, a `location`, and any filters. All fields optional.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Natural-language description of the footage (semantic ranking)."},"location":{"type":"string","description":"A place — landmark, neighborhood, or city, e.g. \"Brooklyn Bridge\". Smart-resolved to a search radius; finds nearby clips regardless of how each was tagged."},"radius_km":{"type":"number","default":2,"description":"Radius in km around `location`."},"contributor":{"type":"string","description":"Only footage from this contributor, by @handle (public profiles only), e.g. \"@sofi\"."},"classification":{"type":"array","items":{"type":"string","enum":["verified","signed","certified"]},"description":"Verification level(s) to require."},"no_people":{"type":"boolean","description":"True to exclude clips containing people."},"orientation":{"type":"string","enum":["horizontal","vertical"]},"min_resolution":{"type":"string","description":"\"1080p\" | \"4k\" | a pixel height."},"shot_type":{"type":"array","items":{"type":"string","enum":["pov","aerial","static","pan","handheld","tracking"]}},"season":{"type":"string","enum":["winter","spring","summer","autumn"]},"weather":{"type":"array","items":{"type":"string"},"description":"e.g. [\"snow\",\"rain\",\"clear\",\"overcast\",\"fog\"]."},"time_of_day":{"type":"array","items":{"type":"string"},"description":"e.g. [\"golden_hour\",\"afternoon\",\"night\"]."},"country":{"type":"string","description":"e.g. \"Japan\"."},"stamp":{"type":"string","description":"A stamp handle (from /api/facets `stamps`). Restricts to clips carrying that verified place/brand stamp, e.g. footage shot inside Madison Square Garden."},"keywords":{"type":"array","items":{"type":"string"}},"limit":{"type":"integer","minimum":1,"maximum":30,"default":12}}},"examples":{"simple":{"summary":"Just a description","value":{"query":"snowy street at night"}},"geo":{"summary":"Near a landmark, filtered","value":{"query":"water reflections","location":"Brooklyn Bridge","classification":["signed"],"no_people":true,"min_resolution":"4k","limit":12}}}}}},"responses":{"200":{"description":"Ranked clips.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique clip id."},"title":{"type":"string"},"description":{"type":["string","null"],"description":"AI-generated caption of the footage."},"score":{"type":["number","null"],"description":"Relevance 0–1 when the result was ranked by a query/location."},"location":{"type":"string","description":"Where it was shot, e.g. \"Soho, New York\"."},"place":{"type":["string","null"],"description":"Nearest named place / landmark, e.g. \"Brooklyn Bridge\"."},"neighborhood":{"type":["string","null"],"description":"Neighborhood, e.g. \"DUMBO\"."},"contributor":{"type":["object","null"],"description":"Who shot it: { handle, url } for a public profile, or null when the contributor keeps their profile private."},"coordinates":{"type":["string","null"],"description":"\"protected\" for device-verified tiers (an exact point exists, available under license, never published); null for self-attested."},"captured_at":{"type":["string","null"],"format":"date-time"},"duration_seconds":{"type":["number","null"]},"orientation":{"type":"string","enum":["horizontal","vertical"]},"resolution":{"type":["string","null"],"description":"Source resolution, e.g. \"3840x2160\"."},"aspect_ratio":{"type":["string","null"],"description":"e.g. \"16:9\"."},"season":{"type":["string","null"],"description":"winter | spring | summer | autumn (derived from real capture time)."},"time_of_day":{"type":["string","null"],"description":"e.g. golden_hour | afternoon | night."},"weather":{"type":["object","null"],"description":"Captured weather, e.g. { \"summary\": \"snow\", \"temp_c\": -2 }."},"keywords":{"type":"array","items":{"type":"string"}},"has_people":{"type":["boolean","null"]},"classification":{"type":"string","enum":["verified","signed","certified"],"description":"Assurance level (see /classification, the source of truth). verified = a phone-verified real person uploaded a genuine clip; location self-reported. signed = the original file proves both device and embedded GPS. certified = signed in the device Secure Enclave at capture inside the app — tamper-evident. Parallel levels, not quality grades. (Also returned as \"provenance\" for back-compat.)"},"provenance":{"type":"string","enum":["verified","signed","certified"],"description":"Alias of `classification`."},"ai_generated":{"type":"boolean","description":"Always false — real, human-captured footage."},"verified":{"type":"boolean","description":"True when the clip is processed and available."},"thumbnail_url":{"type":"string","format":"uri"},"embed_url":{"type":"string","format":"uri","description":"Vanity inline player to embed in a UI or chat."},"download_url":{"type":"string","format":"uri","description":"Download the file (routes through the site for attribution)."},"page_url":{"type":"string","format":"uri","description":"Human-viewable verified clip page — link here when citing."},"license":{"type":"string","enum":["commercial","editorial"],"description":"\"editorial\" clips contain a recognizable brand/logo, person, or copyrighted work and are NOT cleared for commercial use — fine for reporting, social, research, and AI training."},"commercial_use_ok":{"type":"boolean"},"editorial_reasons":{"type":["array","null"],"items":{"type":"string"}}}}},"count":{"type":"integer"},"message":{"type":"string","description":"Present only when 0 results — a plain-language reason."},"issues":{"type":"array","items":{"type":"string"},"description":"Present only when 0 results — the specific constraints with nothing to match."},"resolved":{"type":"object","description":"Echo of how the server interpreted the request (query, resolved location, filters)."}}}}}},"400":{"description":"Invalid JSON body."},"401":{"description":"Missing/invalid API key."}}}},"/api/facets":{"get":{"operationId":"getFacets","summary":"List every valid filter value","description":"The picker vocabularies (classification, shot_type, setting, season, time_of_day, weather, orientation, min_resolution) plus the countries currently in the library. Use to populate UI controls without hardcoding. Public — no key required.","responses":{"200":{"description":"Facet vocabularies.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/clips/{id}":{"get":{"operationId":"getClip","summary":"Get a single clip by id","parameters":[{"name":"id","in":"path","required":true,"description":"The clip id returned by search.","schema":{"type":"string"}}],"responses":{"200":{"description":"The clip.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique clip id."},"title":{"type":"string"},"description":{"type":["string","null"],"description":"AI-generated caption of the footage."},"score":{"type":["number","null"],"description":"Relevance 0–1 when the result was ranked by a query/location."},"location":{"type":"string","description":"Where it was shot, e.g. \"Soho, New York\"."},"place":{"type":["string","null"],"description":"Nearest named place / landmark, e.g. \"Brooklyn Bridge\"."},"neighborhood":{"type":["string","null"],"description":"Neighborhood, e.g. \"DUMBO\"."},"contributor":{"type":["object","null"],"description":"Who shot it: { handle, url } for a public profile, or null when the contributor keeps their profile private."},"coordinates":{"type":["string","null"],"description":"\"protected\" for device-verified tiers (an exact point exists, available under license, never published); null for self-attested."},"captured_at":{"type":["string","null"],"format":"date-time"},"duration_seconds":{"type":["number","null"]},"orientation":{"type":"string","enum":["horizontal","vertical"]},"resolution":{"type":["string","null"],"description":"Source resolution, e.g. \"3840x2160\"."},"aspect_ratio":{"type":["string","null"],"description":"e.g. \"16:9\"."},"season":{"type":["string","null"],"description":"winter | spring | summer | autumn (derived from real capture time)."},"time_of_day":{"type":["string","null"],"description":"e.g. golden_hour | afternoon | night."},"weather":{"type":["object","null"],"description":"Captured weather, e.g. { \"summary\": \"snow\", \"temp_c\": -2 }."},"keywords":{"type":"array","items":{"type":"string"}},"has_people":{"type":["boolean","null"]},"classification":{"type":"string","enum":["verified","signed","certified"],"description":"Assurance level (see /classification, the source of truth). verified = a phone-verified real person uploaded a genuine clip; location self-reported. signed = the original file proves both device and embedded GPS. certified = signed in the device Secure Enclave at capture inside the app — tamper-evident. Parallel levels, not quality grades. (Also returned as \"provenance\" for back-compat.)"},"provenance":{"type":"string","enum":["verified","signed","certified"],"description":"Alias of `classification`."},"ai_generated":{"type":"boolean","description":"Always false — real, human-captured footage."},"verified":{"type":"boolean","description":"True when the clip is processed and available."},"thumbnail_url":{"type":"string","format":"uri"},"embed_url":{"type":"string","format":"uri","description":"Vanity inline player to embed in a UI or chat."},"download_url":{"type":"string","format":"uri","description":"Download the file (routes through the site for attribution)."},"page_url":{"type":"string","format":"uri","description":"Human-viewable verified clip page — link here when citing."},"license":{"type":"string","enum":["commercial","editorial"],"description":"\"editorial\" clips contain a recognizable brand/logo, person, or copyrighted work and are NOT cleared for commercial use — fine for reporting, social, research, and AI training."},"commercial_use_ok":{"type":"boolean"},"editorial_reasons":{"type":["array","null"],"items":{"type":"string"}}}}}}},"404":{"description":"Clip not found."}}}}}}