{ "openapi": "3.1.0", "info": { "title": "UGC Creator Database API", "version": "0.1.0", "description": "Free database of UGC creators. Search by niche, country, audience, published rates and content style. Free REST API so AI agents can find user-generated content creators for brand videos.\n\nData quality: Best effort, not a guarantee. Every field is read from a public profile or portfolio on the date shown in sources, and it can be out of date, incomplete or wrong — published rates especially, since they are starting prices that change with usage rights, turnaround and scope. Nothing here is an offer or a quote. Confirm price, availability and terms with the creator before relying on them.\n\nDocs: https://ugccreatordatabase.com/for-agents", "contact": { "url": "https://ugccreatordatabase.com/contact" } }, "servers": [ { "url": "https://ugccreatordatabase.com" } ], "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Optional. Raises the rate limit; everything is readable without it." } }, "schemas": { "Creator": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable slug. Use with GET /api/v1/creators/{id}." }, "url": { "type": "string", "format": "uri", "description": "Public profile page you can cite." }, "display_name": { "type": "string" }, "handle": { "type": "string" }, "primary_platform": { "type": "string", "enum": [ "tiktok", "instagram", "youtube", "web" ] }, "platforms": { "type": "object", "additionalProperties": { "type": "object", "properties": { "username": { "type": "string" }, "followers": { "type": [ "integer", "null" ] }, "url": { "type": "string" } } } }, "followers": { "type": "integer", "description": "Followers on the creator's largest platform." }, "bio": { "type": [ "string", "null" ] }, "niches": { "type": "array", "items": { "type": "string" } }, "content_styles": { "type": "array", "items": { "type": "string" } }, "location": { "type": "object", "properties": { "country": { "type": [ "string", "null" ] }, "country_name": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] } } }, "languages": { "type": "array", "items": { "type": "string" } }, "demographics": { "type": "object", "description": "Self-stated only, never inferred.", "properties": { "age_range": { "type": [ "string", "null" ] }, "gender": { "type": [ "string", "null" ] }, "persona_tags": { "type": "array", "items": { "type": "string" } }, "heritage": { "type": "array", "items": { "type": "string" }, "description": "Self-stated nationality or heritage, e.g. 'Ukrainian', 'Italian-American'." } } }, "portfolio": { "type": [ "object", "null" ], "properties": { "url": { "type": "string" }, "type": { "type": [ "string", "null" ] } } }, "links": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } } } }, "rate_usd": { "type": [ "object", "null" ], "description": "Only present when the creator publishes a rate on their own page; null otherwise. A starting price copied from that page on the observed date, not a quote — it changes with usage rights, turnaround and scope, and can be stale. Confirm with the creator.", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" }, "source": { "type": "string", "enum": [ "listed", "declared" ] }, "note": { "type": "string" } } }, "rate_card": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "deliverable": { "type": "string" }, "usd": { "type": "number" }, "notes": { "type": "string" } } } }, "past_brands": { "type": "array", "items": { "type": "string" } }, "contact": { "type": "object", "description": "email (the business address the creator published, or null) and contact_url (their portfolio or link page)." }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "url": { "type": "string" }, "observed_at": { "type": "string" } } }, "description": "Provenance for every profile." } } } } }, "paths": { "/api/v1/creators": { "get": { "operationId": "searchCreators", "summary": "Search UGC creators", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text query, e.g. 'skincare GRWM creator in Texas'. Matched against bios, handles, niche labels and location.", "schema": { "description": "Free-text query, e.g. 'skincare GRWM creator in Texas'. Matched against bios, handles, niche labels and location.", "type": "string", "maxLength": 200 } }, { "name": "niche", "in": "query", "required": false, "description": "Single niche slug. Use list_niches / GET /api/v1/niches for the taxonomy.", "schema": { "description": "Single niche slug. Use list_niches / GET /api/v1/niches for the taxonomy.", "type": "string", "enum": [ "skincare", "beauty", "haircare", "fashion", "fitness", "wellness", "health", "supplements", "food", "beverage", "travel", "home", "parenting", "pets", "tech", "apps", "gaming", "finance", "education", "lifestyle", "outdoors", "automotive", "b2b", "sustainability" ] } }, { "name": "niches", "in": "query", "required": false, "description": "Match creators tagged with ANY of these niche slugs.", "schema": { "type": "string", "description": "Comma-separated niche slugs" } }, { "name": "country", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 country code, e.g. US, GB, CA.", "schema": { "description": "ISO 3166-1 alpha-2 country code, e.g. US, GB, CA.", "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "countries", "in": "query", "required": false, "description": "Match creators in ANY of these ISO-2 countries.", "schema": { "description": "Match creators in ANY of these ISO-2 countries.", "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 } } }, { "name": "region", "in": "query", "required": false, "description": "State / province / region name, e.g. 'California' or 'Texas'.", "schema": { "description": "State / province / region name, e.g. 'California' or 'Texas'.", "type": "string", "maxLength": 60 } }, { "name": "platform", "in": "query", "required": false, "description": "Primary platform of the creator.", "schema": { "description": "Primary platform of the creator.", "type": "string", "enum": [ "tiktok", "instagram", "youtube", "web", "any" ] } }, { "name": "min_followers", "in": "query", "required": false, "description": "Minimum followers on their largest platform. UGC creators are often small; leave unset unless reach matters.", "schema": { "description": "Minimum followers on their largest platform. UGC creators are often small; leave unset unless reach matters.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "max_followers", "in": "query", "required": false, "description": "Maximum followers on their largest platform.", "schema": { "description": "Maximum followers on their largest platform.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "max_rate", "in": "query", "required": false, "description": "Only creators with a published rate (USD per video) at or below this. Creators with no published rate are excluded when this is set.", "schema": { "description": "Only creators with a published rate (USD per video) at or below this. Creators with no published rate are excluded when this is set.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "min_rate", "in": "query", "required": false, "description": "Only creators with a published rate at or above this.", "schema": { "description": "Only creators with a published rate at or above this.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "has_rate", "in": "query", "required": false, "description": "Only creators who publish a rate card.", "schema": { "description": "Only creators who publish a rate card.", "type": "boolean" } }, { "name": "age_range", "in": "query", "required": false, "description": "Self-stated age bracket: 18-24, 25-34, 35-44, 45-54, 55+.", "schema": { "description": "Self-stated age bracket: 18-24, 25-34, 35-44, 45-54, 55+.", "type": "string", "enum": [ "18-24", "25-34", "35-44", "45-54", "55+" ] } }, { "name": "gender", "in": "query", "required": false, "description": "Self-stated gender: female, male, nonbinary.", "schema": { "description": "Self-stated gender: female, male, nonbinary.", "type": "string", "enum": [ "female", "male", "nonbinary" ] } }, { "name": "persona", "in": "query", "required": false, "description": "Self-described persona tag, e.g. mom, student, gen-z, pet-owner, sensitive-skin, athlete, founder.", "schema": { "description": "Self-described persona tag, e.g. mom, student, gen-z, pet-owner, sensitive-skin, athlete, founder.", "type": "string", "enum": [ "mom", "dad", "parent-of-toddler", "parent-of-teen", "student", "gen-z", "millennial", "gen-x", "over-40", "over-50", "couple", "pet-owner", "homeowner", "renter", "plus-size", "petite", "curly-hair", "sensitive-skin", "acne-prone", "mature-skin", "athlete", "runner", "vegan", "nurse", "teacher", "small-business-owner", "founder", "corporate", "military-spouse", "expat", "bilingual", "spanish-speaking" ] } }, { "name": "heritage", "in": "query", "required": false, "description": "Self-stated nationality or heritage, free text, e.g. 'Ukrainian', 'Italian', 'Nigerian-British', 'Mexican-American'. Matched case-insensitively as a substring.", "schema": { "description": "Self-stated nationality or heritage, free text, e.g. 'Ukrainian', 'Italian', 'Nigerian-British', 'Mexican-American'. Matched case-insensitively as a substring.", "type": "string", "maxLength": 40 } }, { "name": "has_portfolio", "in": "query", "required": false, "description": "Only creators with a public portfolio link.", "schema": { "description": "Only creators with a public portfolio link.", "type": "boolean" } }, { "name": "has_email", "in": "query", "required": false, "description": "Only creators with a published business email.", "schema": { "description": "Only creators with a published business email.", "type": "boolean" } }, { "name": "content_style", "in": "query", "required": false, "description": "Content style tag, e.g. talking-head, unboxing, before-after.", "schema": { "description": "Content style tag, e.g. talking-head, unboxing, before-after.", "type": "string", "enum": [ "talking-head", "voiceover", "grwm", "unboxing", "before-after", "tutorial", "asmr", "day-in-the-life", "testimonial", "screen-recording", "product-demo", "comedy", "aesthetic-broll" ] } }, { "name": "sort", "in": "query", "required": false, "description": "relevance (default: creators with portfolios and rates first), followers, recent, rate (lowest published rate first), rate_desc (highest first). Creators with no published rate always sort last under rate and rate_desc.", "schema": { "description": "relevance (default: creators with portfolios and rates first), followers, recent, rate (lowest published rate first), rate_desc (highest first). Creators with no published rate always sort last under rate and rate_desc.", "type": "string", "enum": [ "relevance", "followers", "recent", "rate", "rate_desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, default 20, max 100.", "schema": { "description": "Page size, default 20, max 100.", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset.", "schema": { "description": "Pagination offset.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "security": [ {}, { "ApiKey": [] } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next": { "type": [ "string", "null" ] }, "contact_included": { "type": "boolean" }, "notice": { "type": "string", "description": "Data-quality notice. Pass it on to whoever reads these results." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Creator" } } } } } } } } } }, "/api/v1/creators/{id}": { "get": { "operationId": "getCreator", "summary": "Get one creator", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ {}, { "ApiKey": [] } ], "responses": { "200": { "description": "Creator", "content": { "application/json": { "schema": { "type": "object", "properties": { "creator": { "$ref": "#/components/schemas/Creator" } } } } } }, "404": { "description": "Not found" } } } }, "/api/v1/niches": { "get": { "operationId": "listNiches", "summary": "Niche taxonomy, countries and content styles with counts", "responses": { "200": { "description": "Taxonomy" } } } }, "/api/v1/stats": { "get": { "operationId": "getStats", "summary": "Index size and freshness", "responses": { "200": { "description": "Stats" } } } }, "/api/v1/report": { "post": { "operationId": "reportCreator", "summary": "Flag a wrong record", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "creator_id", "reason" ], "properties": { "creator_id": { "type": "string" }, "reason": { "type": "string", "enum": [ "not_ugc", "wrong_niche", "wrong_location", "inactive", "bad_link", "duplicate", "other" ] }, "detail": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/removal": { "post": { "operationId": "requestRemoval", "summary": "Creator self-service delisting", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "creator_id", "email" ], "properties": { "creator_id": { "type": "string" }, "email": { "type": "string" }, "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Hidden" } } } } } }