{"openapi":"3.1.0","info":{"title":"Influesque API","version":"1.0.0","summary":"Read-only access to YouTube creator, sponsor and audience intelligence.","description":"The Influesque API exposes the same YouTube creator, sponsor and audience data as\nthe Influesque app and MCP server, over plain HTTP + JSON.\n\n## Authentication\nSend your personal API key as a Bearer token:\n\n```\nAuthorization: Bearer ifsk_your_key_here\n```\n\nGenerate a key under **Settings → API \u0026 MCP**. The same key authenticates both this\nREST API and the MCP server.\n\n## Credits\nBillable calls draw from your plan's monthly credit allowance. Searching creators or\nsponsors and fetching a profile or audience each cost **1 credit**; listing niches and\nchecking your own credit balance are **free**. When you run out, billable calls return\n`402 Payment Required` until your allowance renews or you top up.\n\n## Rate limits \u0026 fair use\nRequests are capped per API key per minute (HTTP `429` when exceeded) and per IP at the\nedge. The API is built for targeted lookups, not bulk export: results are paginated and\ncapped per page, and there is no list-all endpoint.\n","contact":{"name":"Influesque","url":"https://influesque.com","email":"support@influesque.com"}},"servers":[{"url":"https://platform.influesque.com","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Creators","description":"Search creators and fetch profiles and audience demographics."},{"name":"Sponsors","description":"Search brands/sponsors and fetch full brand profiles."},{"name":"Reference","description":"Supporting reference data (niches). Free."},{"name":"Account","description":"Your own account (credit balance). Free."}],"paths":{"/api/v1/creators":{"get":{"tags":["Creators"],"operationId":"searchCreators","summary":"Search creators","description":"Search YouTube creators by topic/keyword/brand plus optional typed filters. Returns\na relevance-ranked, paginated list of creator summaries (up to 25 per page). If\n`hasMore` is true, request the next page with `page=\u003cnextPage\u003e`. Costs 1 credit per page.\n","x-creditCost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Short topic/keyword/brand terms only (e.g. \"travel adventure vlogs\"). No sentences or filters.","schema":{"type":"string"}},{"name":"niche_category","in":"query","description":"Content category value (see `/api/v1/niches`), e.g. `gaming`. Matches the niche even as a secondary niche.","schema":{"type":"string"}},{"name":"primary_niche_only","in":"query","description":"When true, only creators whose primary (dominant) niche matches `niche_category`.","schema":{"type":"boolean"}},{"name":"country","in":"query","description":"Creator country: full name or ISO code (e.g. \"Netherlands\" or \"NL\").","schema":{"type":"string"}},{"name":"language","in":"query","schema":{"type":"string"}},{"name":"min_subscribers","in":"query","schema":{"type":"integer"}},{"name":"max_subscribers","in":"query","schema":{"type":"integer"}},{"name":"min_avg_views","in":"query","schema":{"type":"integer"}},{"name":"min_engagement_rate","in":"query","description":"Minimum engagement rate as a percent, e.g. 3 for 3%.","schema":{"type":"number"}},{"name":"has_sponsors","in":"query","description":"Only creators with detected sponsorships.","schema":{"type":"boolean"}},{"name":"video_format","in":"query","schema":{"type":"string","enum":["short","long"]}},{"name":"sort","in":"query","description":"Reorders the whole match set by a raw metric. Omit to keep relevance ranking.","schema":{"type":"string","enum":["subs_desc","subs_asc","views_desc","avg_views_desc","engagement_desc"]}},{"name":"page","in":"query","description":"1-based page number. Each page costs 1 credit.","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"A page of creator summaries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchCreatorsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/api/v1/creators/{id}":{"get":{"tags":["Creators"],"operationId":"getCreator","summary":"Get a creator profile","description":"Full profile for one creator: stats, niches, social links and full sponsor history.\n`id` may be a YouTube handle (with or without `@`), a channel id (`UC…`), or the\n`creator-\u003cid\u003e` slug returned by search. Costs 1 credit.\n","x-creditCost":1,"parameters":[{"$ref":"#/components/parameters/CreatorId"}],"responses":{"200":{"description":"The creator profile.","content":{"application/json":{"schema":{"type":"object","properties":{"creator":{"$ref":"#/components/schemas/CreatorDetail"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/api/v1/creators/{id}/audience":{"get":{"tags":["Creators"],"operationId":"getCreatorAudience","summary":"Get a creator's audience demographics","description":"Estimated audience demographics (age, gender, geography, language, interests) with a\nconfidence score. `audience` is null when no estimate exists yet. Costs 1 credit.\n","x-creditCost":1,"parameters":[{"$ref":"#/components/parameters/CreatorId"}],"responses":{"200":{"description":"Audience demographics for the creator.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/api/v1/sponsors":{"get":{"tags":["Sponsors"],"operationId":"searchSponsors","summary":"Search sponsors","description":"Find brands/sponsors by name. Returns matching sponsors ranked by how many\nsponsorships Influesque has detected. Costs 1 credit.\n","x-creditCost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Brand/sponsor name or keyword (e.g. \"HelloFresh\").","schema":{"type":"string"}}],"responses":{"200":{"description":"Matching sponsors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchSponsorsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/api/v1/sponsors/{id}":{"get":{"tags":["Sponsors"],"operationId":"getSponsor","summary":"Get a sponsor profile","description":"Full brand profile: website, niches sponsored in, reach/size stats, and the top\ncreators who have worked with the brand. `id` may be a numeric sponsor id (from\nsearch) or a brand name. Costs 1 credit.\n","x-creditCost":1,"parameters":[{"name":"id","in":"path","required":true,"description":"Numeric sponsor id (from search) or a brand name.","schema":{"type":"string"}}],"responses":{"200":{"description":"The sponsor profile.","content":{"application/json":{"schema":{"type":"object","properties":{"sponsor":{"$ref":"#/components/schemas/SponsorDetail"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/api/v1/niches":{"get":{"tags":["Reference"],"operationId":"listNiches","summary":"List niche categories","description":"The valid niche/content categories and their filter values for `niche_category`. Free (no credit cost).","x-creditCost":0,"responses":{"200":{"description":"All niche categories.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NichesResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/api/v1/credits":{"get":{"tags":["Account"],"operationId":"getCredits","summary":"Check your credit balance","description":"Your current credit balance and plan. Free (no credit cost).","x-creditCost":0,"responses":{"200":{"description":"Your credit balance and plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key (ifsk_…)","description":"Personal API key generated under Settings → API \u0026 MCP."}},"parameters":{"CreatorId":{"name":"id","in":"path","required":true,"description":"YouTube handle (with or without `@`), channel id (`UC…`), or the `creator-\u003cid\u003e` slug from search.","schema":{"type":"string"}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Your plan has no API access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PaymentRequired":{"description":"Out of credits. Upgrade or top up to continue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidRequest":{"description":"A required parameter is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Rate limit exceeded. Slow down and retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["out_of_credits"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"CreatorSummary":{"type":"object","description":"Lightweight creator view used in search results and sponsor profiles.","properties":{"id":{"type":"string","description":"Stable slug (handle, or creator-\u003cid\u003e when handle-less).","examples":["mrbeast"]},"name":{"type":"string"},"handle":{"type":"string"},"influesqueUrl":{"type":"string","format":"uri"},"youtubeUrl":{"type":["string","null"],"format":"uri"},"country":{"type":["string","null"]},"language":{"type":["string","null"]},"verified":{"type":"boolean"},"primaryNiche":{"type":["string","null"]},"topSponsors":{"type":"array","items":{"type":"string"}},"subscribers":{"type":"integer"},"avgViews":{"type":"integer"},"totalViews":{"type":"integer"},"videoCount":{"type":"integer"},"engagementRate":{"type":["number","null"]}}},"CreatorDetail":{"allOf":[{"$ref":"#/components/schemas/CreatorSummary"},{"type":"object","properties":{"description":{"type":["string","null"]},"niches":{"type":"array","items":{"type":"string"}},"sponsors":{"type":"array","items":{"$ref":"#/components/schemas/CreatorSponsor"}},"links":{"type":"object","description":"Social/contact links (only instagram, twitter, tiktok, website are exposed).","additionalProperties":{"type":"string"}}}}]},"CreatorSponsor":{"type":"object","properties":{"name":{"type":"string"},"website":{"type":["string","null"]},"influesqueUrl":{"type":"string","format":"uri"},"sponsorshipCount":{"type":"integer"},"lastSeen":{"type":["string","null"],"format":"date"}}},"SearchCreatorsResponse":{"type":"object","properties":{"query":{"type":"string"},"page":{"type":"integer"},"totalFound":{"type":"integer"},"returned":{"type":"integer"},"hasMore":{"type":"boolean"},"nextPage":{"type":["integer","null"]},"creators":{"type":"array","items":{"$ref":"#/components/schemas/CreatorSummary"}}}},"AudienceResponse":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"handle":{"type":"string"},"note":{"type":"string","description":"Present when no audience estimate exists yet."},"audience":{"oneOf":[{"$ref":"#/components/schemas/Audience"},{"type":"null"}]}}},"Audience":{"type":"object","properties":{"ageDistribution":{"type":"object","additionalProperties":{"type":"number"}},"genderDistribution":{"type":"object","additionalProperties":{"type":"number"}},"geoDistribution":{"type":"object","additionalProperties":{"type":"number"}},"languageDistribution":{"type":"object","additionalProperties":{"type":"number"}},"interests":{"type":"array","items":{"type":"string"}},"confidence":{"type":"number"},"confidenceLabel":{"type":"string"},"estimated":{"type":"boolean"},"computedAt":{"type":["string","null"],"format":"date-time"}}},"SponsorSummary":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"kind":{"type":["string","null"]},"website":{"type":["string","null"]},"domain":{"type":["string","null"]},"influesqueUrl":{"type":"string","format":"uri"},"sponsorshipCount":{"type":"integer"},"lastSponsorshipDate":{"type":["string","null"],"format":"date"}}},"SponsorDetail":{"allOf":[{"$ref":"#/components/schemas/SponsorSummary"},{"type":"object","properties":{"description":{"type":["string","null"]},"socialLinks":{"type":["object","null"],"additionalProperties":{"type":"string"}},"stats":{"type":"object","properties":{"creatorCount":{"type":"integer"},"totalReach":{"type":["integer","null"]},"averageCreatorSize":{"type":["number","null"]},"firstSponsorshipDate":{"type":["string","null"],"format":"date"}}},"niches":{"type":"array","items":{"type":"string"}},"topCreators":{"type":"array","items":{"$ref":"#/components/schemas/CreatorSummary"}}}}]},"SearchSponsorsResponse":{"type":"object","properties":{"query":{"type":"string"},"returned":{"type":"integer"},"sponsors":{"type":"array","items":{"$ref":"#/components/schemas/SponsorSummary"}}}},"NichesResponse":{"type":"object","properties":{"niches":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}}}}}},"CreditsResponse":{"type":"object","properties":{"plan":{"type":"string","examples":["user"]},"unlimited":{"type":"boolean"},"balance":{"type":["integer","null"]},"allowance":{"type":"integer"},"renewsAt":{"type":["string","null"],"format":"date-time"}}}}}}