# List Contacted Creators Source: https://docs.topyappers.com/agent-api/endpoint/contacted-creators List creators contacted by your TopYappers outreach agent ## `GET /api/v1/agent/contacted-creators` Returns creators who have received at least one non-failed outbound email from your agent. This is the fastest way to map an inbox email address back to the creator, projects, threads, and reply status. ## Query parameters | Parameter | Type | Description | | ------------------------ | ------- | ------------------------------------------------------------------------------------- | | `projectId` | string | Filter to one agent project. | | `creatorEmail` / `email` | string | Case-insensitive exact creator email match. | | `creatorEmailContains` | string | Case-insensitive partial creator email match. Ignored when `creatorEmail` is present. | | `creatorId` | string | Filter by creator ID. | | `page` | integer | Page number. Default: `1`. | | `perPage` | integer | Results per page. Default: `50`, maximum: `100`. | ```bash cURL theme={null} curl -X GET "https://api.topyappers.com/api/v1/agent/contacted-creators?email=creator@example.com" \ -H "x-ty-api-key: $TY_API_KEY" ``` ```javascript JavaScript theme={null} const params = new URLSearchParams({ email: 'creator@example.com', perPage: '25', }); const res = await fetch( `https://api.topyappers.com/api/v1/agent/contacted-creators?${params.toString()}`, { headers: { 'x-ty-api-key': process.env.TY_API_KEY, }, }, ); const payload = await res.json(); ``` ## Response fields Each item in `response.data` includes: | Field | Description | | ---------------------------------------------------------- | ----------------------------------------------------------------- | | `creator_email` | Email address contacted by the agent. | | `creator_id`, `creator_name`, `creator_platform` | Creator context captured when outreach was sent. | | `project_ids` | Agent project IDs that contacted this creator. | | `thread_ids` | Gmail thread IDs associated with the creator. | | `sent_messages_count` | Number of non-failed outbound messages sent. | | `reply_messages_count` | Number of inbound replies saved for the matching thread or email. | | `has_replies` | `true` when at least one inbound reply exists. | | `first_contacted_at`, `last_contacted_at`, `last_reply_at` | ISO timestamp fields. | | `last_subject`, `last_status`, `last_body_preview` | Preview of the latest outbound message. | ## Example response ```json theme={null} { "message": "OK", "response": { "data": [ { "creator_email": "creator@example.com", "creator_id": "instagram_123", "creator_name": "Creator Name", "creator_platform": "instagram", "project_ids": ["662f01a2c86c2af2a2b9f123"], "thread_ids": ["18f8d5c7a1b12345"], "sent_messages_count": 2, "reply_messages_count": 1, "has_replies": true, "first_contacted_at": "2026-05-01T10:15:00", "last_contacted_at": "2026-05-04T10:15:00", "last_reply_at": "2026-05-05T14:20:00", "last_subject": "Partnership idea", "last_status": "replied", "last_body_preview": "Loved your recent post about meal prep..." } ], "page": 1, "per_page": 50, "next_page": 0, "total_pages": 1, "total": 1 } } ``` # List Agent Messages Source: https://docs.topyappers.com/agent-api/endpoint/messages List sent and received agent email messages ## `GET /api/v1/agent/messages` Returns saved agent email messages. Use this endpoint to retrieve the full conversation history for a creator email or Gmail thread before writing a customized reply. ## Query parameters | Parameter | Type | Description | | ------------------------ | ------- | --------------------------------------------------------------------------------------------------- | | `projectId` | string | Filter to one agent project. | | `creatorEmail` / `email` | string | Case-insensitive exact creator email match. | | `creatorEmailContains` | string | Case-insensitive partial creator email match. Ignored when `creatorEmail` is present. | | `creatorId` | string | Filter by creator ID. | | `threadId` | string | Filter by Gmail thread ID. | | `gmailAccountId` | string | Filter by connected Gmail account ID. | | `direction` | string | `all`, `outbound`, or `inbound`. Default: `all`. Use `outbound` to list messages sent by the agent. | | `status` | string | Filter by stored message status, such as `sent`, `received`, `replied`, or `failed`. | | `isFollowUp` | boolean | Filter follow-up emails. | | `page` | integer | Page number. Default: `1`. | | `perPage` | integer | Results per page. Default: `50`, maximum: `100`. | ```bash cURL theme={null} curl -X GET "https://api.topyappers.com/api/v1/agent/messages?email=creator@example.com&direction=all" \ -H "x-ty-api-key: $TY_API_KEY" ``` ```javascript JavaScript theme={null} const params = new URLSearchParams({ email: 'creator@example.com', direction: 'all', }); const res = await fetch( `https://api.topyappers.com/api/v1/agent/messages?${params.toString()}`, { headers: { 'x-ty-api-key': process.env.TY_API_KEY, }, }, ); const payload = await res.json(); ``` ## Response fields Each item in `response.data` includes: | Field | Description | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | `id` | Message record ID. | | `project_id`, `conversation_id` | Agent project and conversation IDs. | | `gmail_account_id`, `sender_email` | Connected Gmail account context. | | `direction` | `outbound` for agent-sent messages, `inbound` for creator replies. | | `creator_id`, `creator_name`, `creator_email`, `creator_platform` | Creator context saved with the message. | | `subject`, `body`, `body_preview` | Plain-text message content. HTML is converted to readable text when no plain body is saved. | | `status` | Stored message status. | | `sent_at`, `replied_at`, `failed_at`, `date_created`, `date_updated` | ISO timestamp fields. | | `thread_id`, `message_id`, `parent_message_id` | Gmail thread and message identifiers. | | `is_follow_up`, `follow_up_number` | Follow-up metadata. | | `metadata` | Extra transport or workflow metadata. | ## Example response ```json theme={null} { "message": "OK", "response": { "data": [ { "id": "662f0ab2c86c2af2a2b9f456", "project_id": "662f01a2c86c2af2a2b9f123", "sender_email": "partnerships@example.com", "direction": "outbound", "creator_id": "instagram_123", "creator_name": "Creator Name", "creator_email": "creator@example.com", "creator_platform": "instagram", "subject": "Partnership idea", "body_preview": "Loved your recent post about meal prep...", "status": "sent", "thread_id": "18f8d5c7a1b12345", "is_follow_up": false, "date_created": "2026-05-01T10:15:00" } ], "page": 1, "per_page": 50, "next_page": 0, "total_pages": 1, "total": 1 } } ``` # List Agent Projects Source: https://docs.topyappers.com/agent-api/endpoint/projects List your active TopYappers outreach projects ## `GET /api/v1/agent/projects` Returns active agent outreach projects for the API key owner’s team. ```bash cURL theme={null} curl -X GET "https://api.topyappers.com/api/v1/agent/projects" \ -H "x-ty-api-key: $TY_API_KEY" ``` ```javascript JavaScript theme={null} const res = await fetch('https://api.topyappers.com/api/v1/agent/projects', { headers: { 'x-ty-api-key': process.env.TY_API_KEY, }, }); const payload = await res.json(); ``` ## Response fields Each item in `response.data` includes: | Field | Description | | -------------------------------------------------------------- | ----------------------------------------------------------------------- | | `id` | Agent project ID. Use as `projectId` in other Agent Outreach endpoints. | | `name` | Project name. | | `website` / `website_id` | Website connected to the campaign. | | `campaign_id` | CRM campaign ID when linked. | | `status` | Agent status, such as `active`, `paused`, or `disabled`. | | `deal_config` | Structured deal terms used by the agent. | | `target_keywords`, `target_categories`, `target_countries` | Targeting setup. | | `subject_override`, `prompt_override`, `message_body_override` | Custom outreach instructions and overrides. | | `total_emails_sent`, `total_responses`, `total_credits_used` | Project counters. | | `date_created`, `date_updated`, `last_run_at` | ISO timestamp fields. | ## Example response ```json theme={null} { "message": "OK", "response": { "data": [ { "id": "662f01a2c86c2af2a2b9f123", "name": "Spring creator outreach", "website": "example.com", "website_id": "website_123", "campaign_id": "campaign_123", "status": "active", "target_keywords": ["fitness app", "meal prep"], "target_countries": ["United States"], "total_emails_sent": 84, "total_responses": 13, "date_created": "2026-05-01T10:15:00" } ] } } ``` # Agent Outreach API Source: https://docs.topyappers.com/agent-api/overview Access your outreach projects, contacted creators, and email history # Agent Outreach API The Agent Outreach API exposes the email outreach data created by your TopYappers agent. Use it to resolve an inbox email address back to the creator, project, Gmail thread, and previous messages so your team or AI agent can write a more customized reply. ## Base URL `https://api.topyappers.com` ## Authentication All requests require a TopYappers API key in the `x-ty-api-key` header. ```bash theme={null} x-ty-api-key: your-api-key ``` The API key is scoped to the key owner’s team, so responses only include that team’s agent projects and email messages. ## Pricing These endpoints are **free**. They validate your API key and apply rate limits, but they do not consume credits because they return your own outreach data. ## Rate limits * 60 requests per minute per API key. * HTTP `429` responses include `Retry-After`. ## Endpoints | Endpoint | Description | | -------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `GET /api/v1/agent/projects` | List your active agent outreach projects. | | `GET /api/v1/agent/contacted-creators` | List creators contacted by outbound agent email. | | `GET /api/v1/agent/messages` | List email messages, filterable by project, creator email, creator ID, thread, status, and direction. | ## Common workflow 1. Call `GET /api/v1/agent/messages?creatorEmail=creator@example.com&direction=all` with the email address from your inbox. 2. Use the returned `creator_id`, `creator_name`, `project_id`, `thread_id`, and message history to understand context. 3. Optionally call `GET /api/v1/agent/projects` to map the `project_id` to the campaign details. 4. Use `GET /api/v2/creators/search?email=creator@example.com` or `POST /api/v2/creators/get` when you also need the creator’s public profile data. ## Response envelope All Agent Outreach API responses use the standard public API envelope: ```json theme={null} { "message": "OK", "response": { "data": [] } } ``` Paginated endpoints also include `page`, `per_page`, `next_page`, `total_pages`, and `total` inside `response`. # Get Creators (v1) Source: https://docs.topyappers.com/creators-api/endpoint/get GET /api/v1/creators Returns full creator profiles matching filters. Query parameters are identical to GET /api/v2/creators/search (search is free and returns IDs only; this endpoint costs credits per creator returned). # Get Creators by ID (v2) Source: https://docs.topyappers.com/creators-api/endpoint/v2-get POST /api/v2/creators/get Fetch full creator profiles by passing userIds returned from the search endpoint. # Search Creators (v2) Source: https://docs.topyappers.com/creators-api/endpoint/v2-search GET /api/v2/creators/search Search creators using the same filters as the Creators API. Returns a list of userIds to fetch full profiles. # Available Parameters Source: https://docs.topyappers.com/creators-api/parameters Available creators API parameters for the TopYappers API ## Pricing (v1) The v1 Creators API (`GET /api/v1/creators`) costs **1 credit per influencer** returned. ## Response shape (profiles are snake\_case) On `https://api.topyappers.com`, **`GET /api/v1/creators`** returns `{ "message", "params", "response" }`. Full creator rows are in **`response.data`** (not a top-level `data` array). Each creator uses **snake\_case** fields (`user_id`, `handle`, `avg_views`, `promoted_products`, `best_promotion_niches`, `uploads_per_week`, etc.) — see **`openapi.json`** → `Creator` for the full schema and example. **`POST /api/v2/creators/get`** returns `{ "message", "requestedIds", "response" }` with the same creator objects in **`response.data`**. ## Available parameters Query parameters work the same for **`GET /api/v1/creators`** and **`GET /api/v2/creators/search`** (v2 search returns IDs only; filters are identical). For numeric min/max filters, **omit the parameter or use `0`** when you do not want a lower or upper bound (see OpenAPI for exact wording). ### Performance metrics | Parameter | Type | Description | Example | | ------------------- | ------ | -------------------------------------------------------------------------------------------------------------- | ------------------------ | | `followersMin` | Number | Minimum number of followers | `followersMin=10000` | | `followersMax` | Number | Maximum number of followers | `followersMax=1000000` | | `averageViewsMin` | Number | Minimum average views per post | `averageViewsMin=5000` | | `averageViewsMax` | Number | Maximum average views per post | `averageViewsMax=500000` | | `averageLikesMin` | Number | Minimum average likes per post | `averageLikesMin=100` | | `averageLikesMax` | Number | Maximum average likes per post | `averageLikesMax=50000` | | `engagementRateMin` | Number | Minimum engagement rate in percent (`5` means 5%); profile `engagement_rate` uses a fraction (`0.03` means 3%) | `engagementRateMin=2.5` | | `engagementRateMax` | Number | Maximum engagement rate in percent (`5` means 5%); profile `engagement_rate` uses a fraction (`0.03` means 3%) | `engagementRateMax=10` | ### Posting cadence, duration & monetization (sample-based) | Parameter | Type | Description | Example | | ---------------------------- | ------ | ------------------------------------------------------------ | -------------------------------- | | `uploadsPerWeekMin` | Number | Minimum average posts per week | `uploadsPerWeekMin=3` | | `uploadsPerWeekMax` | Number | Maximum average posts per week | `uploadsPerWeekMax=14` | | `uploadsPerMonthMin` | Number | Minimum average posts per month | `uploadsPerMonthMin=10` | | `uploadsPerMonthMax` | Number | Maximum average posts per month | `uploadsPerMonthMax=60` | | `avgVideoDurationSecondsMin` | Number | Minimum average video length (seconds) | `avgVideoDurationSecondsMin=15` | | `avgVideoDurationSecondsMax` | Number | Maximum average video length (seconds) | `avgVideoDurationSecondsMax=120` | | `promotionsCountMin` | Number | Minimum count of promotion-type posts in the analyzed sample | `promotionsCountMin=1` | | `promotionsCountMax` | Number | Maximum promotion posts count | `promotionsCountMax=50` | | `affiliatePostsCountMin` | Number | Minimum affiliate-style posts count | `affiliatePostsCountMin=0` | | `affiliatePostsCountMax` | Number | Maximum affiliate posts count | `affiliatePostsCountMax=20` | | `sponsorshipPostsCountMin` | Number | Minimum sponsored posts count | `sponsorshipPostsCountMin=0` | | `sponsorshipPostsCountMax` | Number | Maximum sponsored posts count | `sponsorshipPostsCountMax=30` | ### Account type, language, hashtags | Parameter | Type | Description | Example | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | `accountType` | String | Creator account type: `faceless`, `ugc`, `agc`, `clipper`, `brand` | `accountType=ugc` | | `language` | String | Primary content language (lowercase): `english`, `spanish`, `french`, `german`, `japanese`, `korean`, `mandarin`, `hindi`, `arabic`, `portuguese`, `russian`, `turkish`, `italian`, `dutch`, `polish`, `thai`, `vietnamese`, `indonesian`, `filipino`, `swedish`, `norwegian`, `danish`, `finnish`, `czech`, `romanian`, `hungarian`, `greek`, `hebrew`, `persian`, `urdu`, `bengali`, `tamil`, `telugu`, `marathi`, `gujarati`, `kannada`, `malayalam`, `punjabi`, `sinhala`, `nepali`, `pashto`, `hausa`, `yoruba`, `somali`, `swahili`, `ukrainian`, `serbian`, `croatian`, `bosnian`, `bulgarian`, `slovak`, `slovenian`, `estonian`, `latvian`, `lithuanian`, `catalan`, `icelandic`, `kazakh`, `uzbek`, `javanese`, `cantonese` | `language=english` | | `hashtags` | String | Comma-separated; **AND** logic — all listed hashtags must appear on the creator. `#` prefix optional | `hashtags=fitness,gym` | ### Demographics | Parameter | Type | Description | Example | | ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------- | | `age` | String | Age buckets (comma-separated): `0-9`, `10-19`, `20-29`, `30-39`, `40-49`, `50-59`, `60-69`, `70-79`, `80-89`, `90-99` | `age=20-29,30-39` | | `gender` | String | `male` or `female` | `gender=female` | | `race` | String | Ethnicity (comma-separated): `White`, `Black`, `Indian`, `East Asian`, `Southeast Asian`, `Middle Eastern`, `Latino Hispanic` | `race=East Asian` | | `hairColor` | String | Hair color (comma-separated): `Blonde hair`, `Brunette hair`, `Black hair`, `Red hair`, `White hair` | `hairColor=Blonde hair` | | `bodyComplexion` | String | Body type (comma-separated): `Skinny`, `Ordinary`, `Overweight`, `Hulk` | `bodyComplexion=Skinny` | ### Content & geography | Parameter | Type | Description | Example | | ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | `mainCategory` | String | Main content category: Arts, Automotive, Beauty & Personal Care, Books & Literature, Business, Finance, Career & Jobs, Collectibles & Hobbies, Community, Ecommerce, Crafts & DIY, Culture, Education, Technology, Entertainment, Environment, Family, Parenting, Fashion, Film, Fitness, Health, Food, Gaming, Gardening & Agriculture, History, Home, Humor, Law, Government, Lifestyle, Marketing, Mental Health, Music, News & Media, Outdoors, Nature, Pets, Animals, Philosophy, Spirituality, Photography, Videography, Politics, Relationships, Religion, Science, Self-Improvement, Shopping, Social Media, Social Issues & Activism, Sports, Travel, Vehicles & Transportation, Virtual Reality, Weapons & Defense, Writing, Kids | `mainCategory=Fashion` | | `subCategory` | String | Sub-category of content (free text search) | `subCategory=streetwear` | | `bio` | String | Keywords in creator's bio | `bio=tiktok shop` | | `promotedProducts` | String | Products or services promoted (comma-separated) | `promotedProducts=beef tallow,feastables` | | `nichesToPromote` | String | Niches to promote — powerful discovery filter (comma-separated) | `nichesToPromote=fashion,streetwear` | | `country` | String | Creator's country (full name) | `country=France` | | `source` | String | Platform: `tiktok`, `instagram`, `youtube`, `twitch`, `linkedin`, `twitter` (X/Twitter) | `source=twitch` | ### Identity, email & pagination | Parameter | Type | Description | Example | | ------------- | ------- | -------------------------------- | ------------------------ | | `username` | String | Filter by handle | `username=mrbeast` | | `emailExists` | Boolean | Only creators with email on file | `emailExists=true` | | `email` | String | Lookup by email | `email=john@example.com` | | `page` | Number | Page number (min 1) | `page=2` | | `perPage` | Number | Results per page (max 100) | `perPage=50` | The full list of allowed values for enums (e.g. `language`, `mainCategory`, `accountType`) matches **`openapi.json`** — use that file as the source of truth if you generate clients or validators. ## Sorting Sorting controls **which creators appear first** in each page. For discovery workflows — especially **"who was added most recently"** — use `sortBy=date_created` with `sortOrder=desc`. | Parameter | Type | Description | | ----------- | ------ | ---------------------------------------------- | | `sortBy` | String | Field to order by (see table below) | | `sortOrder` | String | `asc` (lowest first) or `desc` (highest first) | **Defaults:** `sortBy=date_created`, `sortOrder=desc` (newest first). ### Allowed `sortBy` values | `sortBy` | What it sorts by | | ----------------- | ------------------------------------------------------------------------------------------------- | | `date_created` | When the creator was added or last refreshed. **Use this for "newest in the database" ordering.** | | `followers` | Follower count | | `engagement_rate` | Engagement rate | | `avg_views` | Average views per post | | `avg_likes` | Average likes per post | | `avg_comments` | Average comments per post | ### Examples Newest creators first: ```bash theme={null} sortBy=date_created&sortOrder=desc ``` Largest accounts first: ```bash theme={null} sortBy=followers&sortOrder=desc ``` Micro-influencers first: ```bash theme={null} sortBy=followers&sortOrder=asc ``` ## Promoted Products & Niches to Promote ### promotedProducts Search for creators who have promoted specific products. For example, if you search for "Beef Tallow", you'll get all creators who have mentioned this product in their content. ### nichesToPromote **This is one of the most powerful filters for finding relevant creators.** It's a free text search that matches against our AI-analyzed niches for each creator. * `nichesToPromote=SaaS` - Find creators suitable for promoting software products * `nichesToPromote=skincare,beauty` - Find creators in the skincare/beauty space * `nichesToPromote=fitness supplements` - Find creators who promote fitness-related products ### Tips * Use comma-separated values for multiple items: `promotedProducts=beef tallow,feastables` * `nichesToPromote` works best as a discovery tool - be creative with your search terms # Creators API v2 Source: https://docs.topyappers.com/creators-api/v2 Search creators for free and fetch full profiles with v2 endpoints * Search is free and uses the same filters as the existing Creators API. * Use the `userIds` returned by search to fetch full creator profiles. ## Base URL `https://api.topyappers.com` ## Authentication All requests require an API key in the header: ```bash theme={null} x-ty-api-key: your-api-key ``` ## Pricing | Endpoint | Cost | | ------------------------------------------------ | --------------------------- | | Search creators (`GET /api/v2/creators/search`) | **Free** | | Get creators by ID (`POST /api/v2/creators/get`) | **1 credit per influencer** | ## Rate limits * 60 requests per minute per API key (returns **429** with `Retry-After` when exceeded). ## Workflow 1. **Search** creators with filters (free) → returns `userIds` 2. **Get** creators by passing those `userIds` → returns full creator objects 3. **Paginate** with `page` and `perPage` ## 1) Search creators (free) ``` GET /api/v2/creators/search ``` Headers: * `x-ty-api-key: your-api-key` Query parameters: * Same filters as v1 creators: performance (**followers**, **average views/likes**, **engagement rate**), **posting cadence** (`uploadsPerWeek*`, `uploadsPerMonth*`), **average video duration**, **promotion / affiliate / sponsorship post counts**, **account type**, **language**, **hashtags**, **demographics**, **content & geography**, **email**, **sorting**, and pagination. See [Available parameters](/creators-api/parameters). * Defaults: `page=1`, `perPage=10`. ### Sorting Use `sortBy` and `sortOrder` on the query string the same way as v1 creators. **Default:** `sortBy=date_created`, `sortOrder=desc` (newest / most recently updated in our index first)—important when you care about **date added** or recency rather than only follower size. Full detail, allowed `sortBy` values, and examples: [Sorting (Creators API)](/creators-api/parameters#sorting-creators-api). ```bash cURL theme={null} curl -X GET "https://api.topyappers.com/api/v2/creators/search?source=instagram&country=France&page=1&perPage=10" \ -H "x-ty-api-key: $TY_API_KEY" ``` ```javascript JavaScript theme={null} const params = new URLSearchParams({ source: 'instagram', country: 'France', page: '1', perPage: '10', }); const res = await fetch( `https://api.topyappers.com/api/v2/creators/search?${params.toString()}`, { headers: { 'x-ty-api-key': process.env.TY_API_KEY, }, }, ); const data = await res.json(); // data.response.data => array of userIds to use in the next step ``` Example response: ```json theme={null} { "message": "OK", "params": { "page": 1, "perPage": 10 }, "response": { "data": [ "instagram_57971538386", "instagram_58848167468", "instagram_52172673568", "instagram_74310952606", "instagram_47313147334", "instagram_1101500353", "instagram_67481263644", "instagram_67147724287", "instagram_54567535596", "instagram_9053965104" ], "page": 1, "next_page": 0, "total_pages": 10000 } } ``` ## 2) Get creators by ID ``` POST /api/v2/creators/get ``` Headers: * `x-ty-api-key: your-api-key` * `Content-Type: application/json` Body: ```json theme={null} { "userIds": [ "instagram_57971538386", "instagram_58848167468", "instagram_52172673568" ] } ``` ```bash cURL theme={null} curl -X POST "https://api.topyappers.com/api/v2/creators/get" \ -H "Content-Type: application/json" \ -H "x-ty-api-key: $TY_API_KEY" \ -d '{ "userIds": [ "instagram_57971538386", "instagram_58848167468", "instagram_52172673568" ] }' ``` ```javascript JavaScript theme={null} const body = { userIds: [ 'instagram_57971538386', 'instagram_58848167468', 'instagram_52172673568', ], }; const res = await fetch('https://api.topyappers.com/api/v2/creators/get', { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-ty-api-key': process.env.TY_API_KEY, }, body: JSON.stringify(body), }); const payload = await res.json(); // Creator rows: payload.response.data (each object is snake_case) ``` ### Response shape (public API) `POST /api/v2/creators/get` returns an **envelope**: `message`, `requestedIds` (echo of the ids you sent), and `response` (paginated payload from the backend). Creator profiles live in **`response.data`** — **snake\_case**, same projection as v1. Optional fields may be `null`; `date_created_timestamp` appears when the index provides it. You can also send **`user_ids`** instead of `userIds` in the request body. ```json theme={null} { "message": "OK", "requestedIds": ["UCECuDLnD9j3y901oNxJFerw"], "response": { "data": [ { "user_id": "UCECuDLnD9j3y901oNxJFerw", "handle": "April Apple Tech", "nickname": "April Apple Tech", "bio": "ℹ Tech Review \nℹ Business\nExplore my experience In usage of Gadgets\n…", "source": "youtube", "email": null, "categories": [ "Tech Reviews", "Gadget Reviews", "Smartphone Comparisons", "Business Technology" ], "followers": 2500, "following": 0, "total_videos": 296, "total_likes": 0, "avg_views": 35, "avg_likes": 3, "avg_comments": 1, "engagement_rate": 0.11, "main_website": null, "websites": [], "description": null, "promoted_products": ["DIHRAMS", "iphone"], "best_promotion_niches": [ "Consumer Electronics", "Mobile Devices", "Tech Accessories", "Online Retailers", "Business Software" ], "main_category": "Technology", "country": "United Arab Emirates", "date_created_timestamp": 1775636932.147, "avatar_url": "https://images.0xw.app/avatars/creators/bd6493d02eaf43ad9740efa20ec08cd1.png", "age": "10-19", "gender": "male", "account_type": "ugc", "race": "black", "hair_color": "white", "body_complexion": "hulk", "language": "english", "hashtags": ["iphone17", "cinimaticvideo", "iphoneair", "shotoniphone"], "uploads_per_week": 0.39, "uploads_per_month": 1.66, "avg_video_duration_seconds": null, "promotions_count": 2, "affiliate_posts_count": 0, "sponsorship_posts_count": 0 } ], "page": 1, "next_page": 0, "total_pages": 1 } } ``` `GET /api/v1/creators` uses the same creator objects inside **`response.data`**, with **`params`** instead of `requestedIds`. Field reference: **`openapi.json`** → `components.schemas.Creator` (includes a full `example`). Use `next_page` from the search response to continue fetching IDs, then call `POST /api/v2/creators/get` with those IDs to page through profiles. # Add Creators to CRM List Source: https://docs.topyappers.com/crm-api/endpoint/add-creators POST /api/v2/crm/lists/{list_id}/creators Adds one or more creator IDs to a CRM list. Use `userIds` for all adds. Single-creator adds may include contact metadata such as `contactEmail` and `proposedRate` when `userIds` contains exactly one creator. # Check CRM List Membership Source: https://docs.topyappers.com/crm-api/endpoint/check-creators POST /api/v2/crm/lists/{list_id}/creators/check Checks whether one or more creator IDs already exist in a CRM list. # Create CRM List Source: https://docs.topyappers.com/crm-api/endpoint/create-list POST /api/v2/crm/lists Creates a CRM list in the API key owner's team. Use `name` for the list name. # Delete CRM List Source: https://docs.topyappers.com/crm-api/endpoint/delete-list DELETE /api/v2/crm/lists/{list_id} Soft-deletes a CRM list. # Get CRM List Source: https://docs.topyappers.com/crm-api/endpoint/get-list GET /api/v2/crm/lists/{list_id} # List CRM Creators Source: https://docs.topyappers.com/crm-api/endpoint/list-creators GET /api/v2/crm/lists/{list_id}/creators # List CRM Lists Source: https://docs.topyappers.com/crm-api/endpoint/list-lists GET /api/v2/crm/lists Returns all active CRM lists for the API key owner's team, including creator counts. # Remove Creator from CRM List Source: https://docs.topyappers.com/crm-api/endpoint/remove-creator DELETE /api/v2/crm/lists/{list_id}/creators/{user_id} Soft-removes a creator from a CRM list. # Update CRM Contact Source: https://docs.topyappers.com/crm-api/endpoint/update-contact PATCH /api/v2/crm/contacts/{contact_id} Updates a CRM contact's status and optional contact/deal details. # Update CRM List Source: https://docs.topyappers.com/crm-api/endpoint/update-list PATCH /api/v2/crm/lists/{list_id} # CRM API v2 Source: https://docs.topyappers.com/crm-api/overview Create CRM lists and manage saved creators from your own systems # CRM API v2 The CRM API lets you manage the same creator lists your team uses in the TopYappers app. Use it to create lists, add creators from the Creators API, check whether creators are already saved, move contacts through outreach statuses, and remove creators from a list. ## Base URL `https://api.topyappers.com` ## Authentication All requests require a TopYappers API key in the `x-ty-api-key` header. ```bash theme={null} x-ty-api-key: your-api-key ``` The API key is scoped to the key owner's team, so CRM lists and contacts are only read or changed inside that team. The API key must belong to a user with an active TopYappers subscription. CRM endpoints are free to call, but they are not available to inactive subscriptions. ## Pricing CRM API endpoints are **free for active subscribers**. They validate your API key and subscription status and apply rate limits, but they do not consume credits because they manage your own CRM data. Use `GET /api/v2/creators/search` and `POST /api/v2/creators/get` when you need to discover creators or fetch full creator profiles. ## Rate limits * 60 requests per minute per API key. * HTTP `429` responses include `Retry-After`. * Responses include `x-ty-rate-limit-remaining`, `x-ty-rate-limit-total`, and `x-ty-credits` headers. ## CRM lists In the API, CRM campaigns are exposed as **lists**. | App concept | API name | | ----------------------- | --------- | | CRM campaign/list | `list` | | Creator saved to a list | `contact` | | Creator ID | `user_id` | ## Status values Use these values for `status`: ```text theme={null} TO_OUTREACH OUTREACHED NEGOTIATING WORKING DONE CANCELLED ``` Status input is case-insensitive, so `outreached` is accepted and stored as `OUTREACHED`. ## Common workflow 1. Find creator IDs with `GET /api/v2/creators/search`. 2. Create a CRM list with `POST /api/v2/crm/lists`. 3. Add creators with `POST /api/v2/crm/lists/{list_id}/creators`. 4. Check membership with `POST /api/v2/crm/lists/{list_id}/creators/check`. 5. Update outreach stage with `PATCH /api/v2/crm/contacts/{contact_id}`. ```bash cURL theme={null} curl -X POST "https://api.topyappers.com/api/v2/crm/lists" \ -H "Content-Type: application/json" \ -H "x-ty-api-key: $TY_API_KEY" \ -d '{ "name": "June outreach" }' ``` ```javascript JavaScript theme={null} const listRes = await fetch('https://api.topyappers.com/api/v2/crm/lists', { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-ty-api-key': process.env.TY_API_KEY, }, body: JSON.stringify({ name: 'June outreach' }), }); const listPayload = await listRes.json(); const listId = listPayload.response.id; ``` ```bash cURL theme={null} curl -X POST "https://api.topyappers.com/api/v2/crm/lists/$LIST_ID/creators" \ -H "Content-Type: application/json" \ -H "x-ty-api-key: $TY_API_KEY" \ -d '{ "userIds": [ "instagram_57971538386", "instagram_58848167468" ], "status": "TO_OUTREACH", "notes": "Imported from June creator search" }' ``` ```javascript JavaScript theme={null} await fetch(`https://api.topyappers.com/api/v2/crm/lists/${listId}/creators`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-ty-api-key': process.env.TY_API_KEY, }, body: JSON.stringify({ userIds: ['instagram_57971538386', 'instagram_58848167468'], status: 'TO_OUTREACH', notes: 'Imported from June creator search', }), }); ``` ## Response envelope All CRM API responses use the standard public API envelope: ```json theme={null} { "message": "OK", "response": { "data": [] } } ``` Paginated creator-list responses include `page`, `per_page`, `next_page`, `total_pages`, and `total` inside `response`. ## Endpoints | Endpoint | Description | | ------------------------------------------------------- | ---------------------------------------------- | | `GET /api/v2/crm/lists` | List your CRM lists. | | `POST /api/v2/crm/lists` | Create a CRM list. | | `GET /api/v2/crm/lists/{list_id}` | Get a CRM list. | | `PATCH /api/v2/crm/lists/{list_id}` | Update a CRM list. | | `DELETE /api/v2/crm/lists/{list_id}` | Delete a CRM list. | | `GET /api/v2/crm/lists/{list_id}/creators` | List creators saved to a CRM list. | | `POST /api/v2/crm/lists/{list_id}/creators` | Add one or more creators to a CRM list. | | `POST /api/v2/crm/lists/{list_id}/creators/check` | Check whether creator IDs exist in a CRM list. | | `DELETE /api/v2/crm/lists/{list_id}/creators/{user_id}` | Remove a creator from a CRM list. | | `PATCH /api/v2/crm/contacts/{contact_id}` | Update CRM contact status and details. | # Usage Examples Source: https://docs.topyappers.com/examples Usage examples for the TopYappers API ## Curl ```bash theme={null} curl -X GET "https://api.topyappers.com/api/v1/creators?mainCategory=fashion&followersMin=10000" \\ -H "x-ty-api-key: YOUR_API_KEY" \\ -H "Content-Type: application/json" ``` ## Javascript ```typescript theme={null} const fetchCreators = async () => { const response = await fetch( 'https://api.topyappers.com/api/v1/creators?mainCategory=fashion&followersMin=10000', { headers: { 'x-ty-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' } } ); const data = await response.json(); console.log(data); }; fetchCreators(); ``` ## Python ```python theme={null} import requests url = "https://api.topyappers.com/api/v1/creators" params = { "mainCategory": "fashion", "followersMin": 10000 } headers = { "x-ty-api-key": "YOUR_API_KEY", "Content-Type": "application/json" } response = requests.get(url, params=params, headers=headers) data = response.json() print(data) ``` # TopYappers API Source: https://docs.topyappers.com/index Build creator search, viral content discovery, media remixing, CRM, and outreach workflows with the TopYappers API. # TopYappers API Use TopYappers APIs to discover creators, analyze high-performing content, remix media, manage creator CRM records, and retrieve outreach activity. Search creators for free, then fetch full profiles for the creators you need. Find viral posts, creative patterns, and content ideas for research workflows. Process video and image URLs through the Remix API with optional transformation parameters. Manage creator lists, check membership, and update contact records. Retrieve outreach projects, contacted creators, and saved email messages. Discover trending songs and audio context for content research. ## Quickstart 1. Create or copy an API key from your [TopYappers dashboard](https://www.topyappers.com/profile). 2. Send the key in the `x-ty-api-key` header. 3. Start with the free creator search endpoint, then fetch full records only for the creators you need. ```bash theme={null} curl "https://api.topyappers.com/api/v2/creators/search?mainCategory=technology&followersMin=10000" \ -H "x-ty-api-key: YOUR_API_KEY" ``` Use `GET /api/v2/creators/search` to discover creator IDs for free, then call `POST /api/v2/creators/get` when you need full profiles. ## Common Paths Free creator discovery with filters for niche, source, country, follower count, and more. Retrieve complete creator profiles by ID. Submit a public video URL for Remix API processing. Submit one image URL or a batch of image URLs for Remix API processing. ## Usage Understand credit costs, rate-limit headers, and retry behavior. Reference supported enum values used across filters and request bodies. # Rate Limits Source: https://docs.topyappers.com/rate-limits Rate limits for the TopYappers API ## Rate Limits All API endpoints are rate limited. The rate limit is 60 requests per minute. You will receive a 429 status code if you exceed the rate limit. ## API Key You can get an API key from the TopYappers platform - [https://www.topyappers.com/profile](https://www.topyappers.com/profile) ## Contact Us If you need to increase the rate limit, please contact us. # Enums Source: https://docs.topyappers.com/reference/enums Reference lists for API filter values # Enums This page contains all available enum values you can use when filtering API requests. ## Categories Content categories for filtering creators and viral content. ```json theme={null} [ "Arts", "Automotive", "Beauty & Personal Care", "Books & Literature", "Business", "Finance", "Career & Jobs", "Collectibles & Hobbies", "Community", "Ecommerce", "Crafts & DIY", "Culture", "Education", "Technology", "Entertainment", "Environment", "Family", "Parenting", "Fashion", "Film", "Fitness", "Health", "Food", "Gaming", "Gardening & Agriculture", "History", "Home", "Humor", "Law", "Government", "Lifestyle", "Marketing", "Mental Health", "Music", "News & Media", "Outdoors", "Nature", "Pets", "Animals", "Philosophy", "Spirituality", "Photography", "Videography", "Politics", "Relationships", "Religion", "Science", "Self-Improvement", "Shopping", "Social Media", "Social Issues & Activism", "Sports", "Travel", "Vehicles & Transportation", "Virtual Reality", "Weapons & Defense", "Writing", "Kids" ] ``` ## Countries Available countries for geographic filtering. ```json theme={null} [ "United States", "China", "Japan", "Germany", "United Kingdom", "India", "France", "Canada", "Italy", "South Korea", "Australia", "Brazil", "Spain", "Mexico", "Indonesia", "Netherlands", "Saudi Arabia", "Turkey", "Switzerland", "Taiwan", "Poland", "Sweden", "Belgium", "Thailand", "Argentina", "Nigeria", "Austria", "Iran", "Norway", "United Arab Emirates", "Ireland", "Israel", "South Africa", "Denmark", "Singapore", "Malaysia", "Philippines", "Hong Kong", "Colombia", "Bangladesh", "Egypt", "Finland", "Chile", "Vietnam", "Czechia", "Romania", "New Zealand", "Portugal", "Greece", "Iraq", "Qatar", "Peru", "Hungary", "Kuwait", "Ukraine", "Morocco", "Slovakia", "Puerto Rico", "Ecuador", "Oman", "Kenya", "Luxembourg", "Cuba", "Sri Lanka", "Uzbekistan", "Bulgaria", "Croatia", "Côte d'Ivoire", "Belarus", "Uruguay", "Panama", "Slovenia", "Turkmenistan", "Lithuania", "Lebanon", "Tanzania", "Jordan", "Bahrain", "Serbia", "Cameroon", "Bolivia", "Paraguay", "Ghana", "Estonia", "Uganda", "Zambia", "Afghanistan", "Bosnia and Herzegovina", "Mozambique", "Armenia", "Georgia", "Honduras", "Albania", "Madagascar", "Namibia", "Senegal", "Malta", "Chad", "Niger", "Mali", "Kyrgyzstan", "Malawi", "Rwanda", "Burundi", "Comoros", "Lesotho", "Tajikistan", "Suriname", "Montenegro", "Eswatini", "Sierra Leone", "Gambia", "Guyana", "Timor-Leste", "Mauritania", "Burkina Faso", "Liberia", "Cape Verde", "Mauritius", "Bhutan", "Benin", "Central African Republic", "Togo", "Guinea", "Gabon", "São Tomé and Príncipe", "Equatorial Guinea", "Antigua and Barbuda", "Belize", "Barbados", "Saint Kitts and Nevis", "Vanuatu", "Solomon Islands", "Saint Vincent and the Grenadines", "Fiji", "Samoa", "Tonga", "Dominica", "Russia", "Other" ] ``` ## Account type Filter creators by account classification (`accountType` query parameter). Values are lowercase strings. | Value | Meaning | | ---------- | -------------------------------------------------------------- | | `faceless` | Anonymous or faceless accounts without a strong personal brand | | `ugc` | User-generated content creators | | `agc` | AI-generated content creators | | `clipper` | Clipping / repost / compilation-style accounts | | `brand` | Official brand accounts | ```json theme={null} ["faceless", "ugc", "agc", "clipper", "brand"] ``` ## Languages Primary content language for creator filtering (`language` query parameter). Use **lowercase** values as shown—this matches the Creators API and the dashboard language picker (labels are Title Case in the UI). Language tagging is still expanding; not every creator has a value yet. ```json theme={null} [ "arabic", "bengali", "bosnian", "bulgarian", "cantonese", "catalan", "croatian", "czech", "danish", "dutch", "english", "estonian", "filipino", "finnish", "french", "german", "greek", "gujarati", "hausa", "hebrew", "hindi", "hungarian", "icelandic", "indonesian", "italian", "japanese", "javanese", "kannada", "kazakh", "korean", "latvian", "lithuanian", "malay", "malayalam", "mandarin", "marathi", "nepali", "norwegian", "pashto", "persian", "polish", "portuguese", "punjabi", "romanian", "russian", "serbian", "sinhala", "slovak", "slovenian", "somali", "spanish", "swahili", "swedish", "tamil", "telugu", "thai", "turkish", "ukrainian", "urdu", "uzbek", "vietnamese", "yoruba" ] ``` ## Age groups Estimated creator age ranges (`age` query parameter). Pass one or more ranges as a comma-separated string, for example `age=20-29,30-39`. ```json theme={null} ["0-9", "10-19", "20-29", "30-39", "40-49", "50-59", "60-69", "70-79", "80-89", "90-99"] ``` ## Sources Available data sources for creator filtering. ```json theme={null} ["tiktok", "instagram", "youtube", "twitch", "linkedin", "twitter"] ``` ## Gender Available gender options for creator filtering. ```json theme={null} ["male", "female"] ``` ## Hair colors Values as used in the app and API filters (`hairColor` query parameter). Multiple values can be comma-separated. ```json theme={null} ["Blonde hair", "Brunette hair", "Black hair", "Red hair", "White hair"] ``` ## Races Race / ethnicity options for creator filtering (`race` query parameter). Multiple values can be comma-separated. ```json theme={null} ["White", "Black", "Indian", "East Asian", "Southeast Asian", "Middle Eastern", "Latino Hispanic"] ``` ## Body complexions Body type / build options for creator filtering (`bodyComplexion` query parameter). Multiple values can be comma-separated. ```json theme={null} ["Skinny", "Ordinary", "Overweight", "Hulk"] ``` # Rate Limits & Credits Source: https://docs.topyappers.com/reference/rate-limits-credits Understanding API pricing, credits, and rate limits # Rate Limits & Credits This page explains how credits and rate limits work across all TopYappers APIs. ## Credits Pricing Each API call consumes credits based on the data returned: | API | Endpoint | Cost | | ---------------------- | ----------------------------- | --------------------------------- | | **Creators API v1** | `GET /api/v1/creators` | 1 credit per creator | | **Creators API v2** | `GET /api/v2/creators/search` | **Free** | | **Creators API v2** | `POST /api/v2/creators/get` | 1 credit per creator | | **CRM API v2** | `/api/v2/crm/*` | **Free with active subscription** | | **Viral Content API** | `POST /api/v1/viral-content` | 1 credit per content | | **Songs API** | `GET /api/v1/songs` | 10 credits per request | | **Agent Outreach API** | `GET /api/v1/agent/*` | **Free** | **Save credits with v2!** Use the Creators API v2 search endpoint for free to find creator IDs, then only pay for the specific creators you need. ## Rate Limits All API endpoints are rate limited to **60 requests per minute** per API key. When you exceed the rate limit, you'll receive a `429 Too Many Requests` response with a `Retry-After` header indicating how many seconds to wait. ```json theme={null} { "error": "Too many requests", "retryAfter": 45 } ``` ## Response Headers Every API response includes headers to help you track your usage: ### `x-ty-credits` Your remaining credit balance after the request. ``` x-ty-credits: 4523 ``` ### `x-ty-rate-limit-remaining` Number of requests remaining in the current rate limit window (resets every minute). ``` x-ty-rate-limit-remaining: 55 ``` ### `x-ty-rate-limit-total` Your total rate limit allocation per minute. Default is 60 requests/minute. ``` x-ty-rate-limit-total: 60 ``` **Need higher rate limits?** If you require increased rate limits for your use case, please [contact support](mailto:support@topyappers.com) to discuss enterprise options. ## Example Response Headers ```http theme={null} HTTP/1.1 200 OK Content-Type: application/json x-ty-credits: 4523 x-ty-rate-limit-remaining: 55 x-ty-rate-limit-total: 60 ``` ## Handling Rate Limits Here's how to properly handle rate limits in your code: ```javascript JavaScript theme={null} async function fetchWithRateLimitHandling(url, options) { const response = await fetch(url, options); // Check remaining credits const credits = response.headers.get('x-ty-credits'); console.log(`Credits remaining: ${credits}`); // Check rate limit const rateLimit = response.headers.get('x-ty-rate-limit-remaining'); console.log(`Requests remaining this minute: ${rateLimit}`); // Handle rate limit exceeded if (response.status === 429) { const data = await response.json(); const retryAfter = data.retryAfter || 60; console.log(`Rate limited. Retrying in ${retryAfter} seconds...`); await new Promise(resolve => setTimeout(resolve, retryAfter * 1000)); return fetchWithRateLimitHandling(url, options); } return response; } ``` ```python Python theme={null} import requests import time def fetch_with_rate_limit_handling(url, headers): response = requests.get(url, headers=headers) # Check remaining credits credits = response.headers.get('x-ty-credits') print(f"Credits remaining: {credits}") # Check rate limit rate_limit = response.headers.get('x-ty-rate-limit-remaining') print(f"Requests remaining this minute: {rate_limit}") # Handle rate limit exceeded if response.status_code == 429: data = response.json() retry_after = data.get('retryAfter', 60) print(f"Rate limited. Retrying in {retry_after} seconds...") time.sleep(retry_after) return fetch_with_rate_limit_handling(url, headers) return response ``` ## Best Practices Check the `x-ty-credits` header regularly to avoid running out of credits mid-operation. The v2 search endpoint is free - use it to find exactly the creators you need before fetching full profiles. When you hit rate limits, respect the `retryAfter` value and implement exponential backoff. Use pagination efficiently and batch your requests to stay within rate limits. # Upload Video for Remix Source: https://docs.topyappers.com/remix-api/endpoint/get POST /api/v1/remix Process a video from a provided URL. The API will download the video, apply transformations, and remove invisible watermarks. # Upload Images for Remix Source: https://docs.topyappers.com/remix-api/endpoint/image-rewrite POST /api/v1/image-rewrite Process one or more images from provided URLs. The API will download the images, apply transformations, and remove invisible watermarks. # Remix API Overview Source: https://docs.topyappers.com/remix-api/overview Process videos and images with the TopYappers Remix API **Remove Invisible Watermarks from AI-Generated Media** The Remix API helps you remove invisible watermarks that AI media generation platforms add to their content. Process videos or images through our API to get clean output for your use cases. ## Introduction The Remix API allows you to process video and image files by providing public media URLs. The API downloads the media from the provided URL, applies your specified transformations, and processes it to remove invisible watermarks. **Upload Your Media First** Before using the Remix API, upload your video or image file to cloud storage such as **Cloudflare R2** or **AWS S3** and make it publicly accessible. The API requires direct URLs to your media files. ## Authentication All requests to the Remix API require authentication using an API key passed in the `x-ty-api-key` header. ```bash theme={null} x-ty-api-key: your-api-key-here ``` ## Endpoints ```bash Video theme={null} POST https://www.topyappers.com/api/v1/remix ``` ```bash Images theme={null} POST https://www.topyappers.com/api/v1/image-rewrite ``` ## How to Upload Your Media Before using the Remix API, you need to upload your media to cloud storage. Here are the recommended options: ### Option 1: Cloudflare R2 Storage Cloudflare R2 offers S3-compatible storage with no egress fees. 1. Create an R2 bucket in your Cloudflare dashboard 2. Upload your video or image file to the bucket 3. Make the bucket or object publicly accessible 4. Use the public URL in your API request **Example R2 URLs**: `https://pub-abc123.r2.dev/my-video.mp4`, `https://pub-abc123.r2.dev/image-1.jpg` ### Option 2: AWS S3 Storage AWS S3 is a widely-used object storage service. 1. Create an S3 bucket in your AWS console 2. Upload your video or image file to the bucket 3. Configure the bucket policy or object ACL to allow public read access 4. Use the public URL in your API request **Example S3 URLs**: `https://my-bucket.s3.amazonaws.com/my-video.mp4`, `https://my-bucket.s3.amazonaws.com/image-1.jpg` ### Other Storage Options Any cloud storage service that provides publicly accessible URLs will work, including: * Google Cloud Storage * Azure Blob Storage * DigitalOcean Spaces * Backblaze B2 **Security Note**: Only make media publicly accessible that you're comfortable sharing. Consider using signed URLs with expiration times for sensitive content. ## Request Format ### Video Request `POST /api/v1/remix` accepts JSON with the following fields: | Field | Type | Required | Description | | ------------ | ------ | -------- | --------------------------------------------------- | | `video_url` | String | Yes | URL to the video file (must be publicly accessible) | | `parameters` | Object | No | Optional processing parameters | ### Video Processing Parameters The `parameters` field accepts an object with optional processing parameters. All parameters are optional and will use default values if not specified. | Parameter | Type | Default | Range/Values | Description | | ---------------------- | ------- | ------------- | -------------------------- | -------------------------------------------- | | `zoomFactor` | number | 1.0 | 0.1 - 5.0 | Zoom level for the video | | `hue` | number | 0.0 | -180 to 180 | Hue adjustment in degrees | | `playbackSpeed` | number | 1.0 | 0.1 - 5.0 | Video playback speed multiplier | | `saturation` | number | 1.0 | 0.0 - 3.0 | Color saturation multiplier | | `brightness` | number | 0.0 | -1.0 to 1.0 | Brightness adjustment | | `contrast` | number | 1.0 | 0.0 - 3.0 | Contrast multiplier | | `volume` | number | 1.0 | 0.0 - 2.0 | Audio volume multiplier | | `removeAudio` | boolean | false | true/false | Whether to remove audio from the video | | `algorithmFingerprint` | string | "Fingerprint" | Any string | Algorithm identifier for processing | | `deviceMedia` | string | - | See supported values below | Target device profile for media optimization | | `hueShift` | number | 0.0 | -180 to 180 | Additional hue shift in degrees | | `gamma` | number | 1.0 | 0.1 - 3.0 | Gamma correction value | | `temperature` | number | 1.0 | 0.5 - 2.0 | Color temperature adjustment | | `noise` | number | 0.0 | 0.0 - 1.0 | Amount of noise to add | | `sharpness` | number | 1.0 | 0.0 - 3.0 | Sharpness multiplier | | `blend` | number | 0.0 | 0.0 - 1.0 | Blending amount | | `bilateVariation` | number | 1.0 | 0.0 - 2.0 | Bilateral filter variation | | `frameBlending` | number | 0.0 | 0.0 - 1.0 | Amount of frame blending | | `timeShift` | number | 0.0 | -10.0 to 10.0 | Time shift in seconds | #### Supported `deviceMedia` Values ```typescript theme={null} export enum DeviceModel { IPHONE_17_PRO_MAX = "iPhone 17 Pro Max", IPHONE_17_PRO = "iPhone 17 Pro", IPHONE_17 = "iPhone 17", IPHONE_16_PRO_MAX = "iPhone 16 Pro Max", IPHONE_16_PRO = "iPhone 16 Pro", IPHONE_16 = "iPhone 16", IPHONE_15_PRO_MAX = "iPhone 15 Pro Max", IPHONE_15_PRO = "iPhone 15 Pro", IPHONE_15 = "iPhone 15", IPHONE_14_PRO_MAX = "iPhone 14 Pro Max", IPHONE_14_PRO = "iPhone 14 Pro", IPHONE_14 = "iPhone 14", IPHONE_13_PRO_MAX = "iPhone 13 Pro Max", IPHONE_13_PRO = "iPhone 13 Pro", IPHONE_13 = "iPhone 13", META_RAYBAN = "Ray-Ban Meta Smart Glasses", } ``` #### Example with Multiple Parameters ```json theme={null} { "video_url": "https://pub-abc123.r2.dev/my-video.mp4", "parameters": { "playbackSpeed": 1.2, "brightness": 0.1, "contrast": 1.1, "saturation": 1.2, "hue": 15, "zoomFactor": 1.05, "removeAudio": false, "deviceMedia": "iPhone 16 Pro" } } ``` ### Image Request `POST /api/v1/image-rewrite` accepts either a single `image_url` or an `images` array for batch processing. | Field | Type | Required | Description | | ------------ | ------ | ----------------------------------- | ------------------------------------------------------------------------------ | | `image_url` | String | Yes, unless `images` is provided | URL to a single image file | | `images` | Array | Yes, unless `image_url` is provided | Up to 20 image objects with `image_url` and optional image-specific parameters | | `parameters` | Object | No | Optional global image processing parameters applied to every image | #### Image Processing Parameters | Parameter | Type | Default | Range/Values | Description | | ---------------- | ------- | ------- | -------------------------- | -------------------------------------- | | `zoomFactor` | number | 1.0 | 0.5 - 2.0 | Zoom level for the image | | `saturation` | number | 1.0 | 0.0 - 2.0 | Color saturation multiplier | | `brightness` | number | 0.0 | -1.0 to 1.0 | Brightness adjustment | | `contrast` | number | 1.0 | 0.0 - 2.0 | Contrast multiplier | | `hue` | number | 0.0 | -180 to 180 | Hue adjustment in degrees | | `hueShift` | number | 0.0 | -180 to 180 | Alias for hue adjustment | | `gamma` | number | 1.0 | 0.1 - 3.0 | Gamma correction value | | `temperature` | number | 1.0 | 0.1 - 2.0 | Color temperature adjustment | | `noise` | number | 0.0 | 0.0 - 0.5 | Amount of noise to add | | `sharpness` | number | 1.0 | 0.0 - 2.0 | Sharpness multiplier | | `quality` | integer | 94 | 60 - 100 | Output image quality | | `flipHorizontal` | boolean | false | true/false | Whether to flip the image horizontally | | `flipVertical` | boolean | false | true/false | Whether to flip the image vertically | | `deviceModel` | string | - | See supported values above | Target device profile for metadata | #### Image Batch Example ```json theme={null} { "images": [ { "image_url": "https://pub-abc123.r2.dev/image-1.jpg" }, { "image_url": "https://pub-abc123.r2.dev/image-2.jpg", "brightness": 0.03 } ], "parameters": { "brightness": 0.02, "contrast": 1.05, "quality": 94, "deviceModel": "iPhone 16 Pro" } } ``` ## Response Format ### Success Response (200 OK) #### Video ```json theme={null} { "data": { "inputVideoUrl": "https://storage.topyappers.com/uploads/abc123.mp4", "result": "Video processing initiated" } } ``` #### Images ```json theme={null} { "success": true, "message": "Images processed successfully", "data": { "imageCount": 2, "inputImageUrls": [ "https://pub-abc123.r2.dev/image-1.jpg", "https://pub-abc123.r2.dev/image-2.jpg" ], "processedImages": [ { "url": "https://imgrework.topyappers.com/processed-image-1.jpg", "applied_params": { "brightness": 0.02, "contrast": 1.05, "quality": 94 } } ], "processingTime": 8.42 } } ``` ### Error Responses * **400 Bad Request**: Invalid media URL or parameters * **401 Unauthorized**: Invalid or missing API key * **413 Payload Too Large**: Video file exceeds size limit * **429 Too Many Requests**: Rate limit exceeded ## Code Examples ```python Python theme={null} import requests import json API_KEY = "your-api-key-here" BASE_URL = "https://www.topyappers.com" # Video URL from Cloudflare R2 or AWS S3 VIDEO_URL = "https://pub-abc123.r2.dev/my-video.mp4" # Optional parameters for video processing parameters = { "playbackSpeed": 1.2, "brightness": 0.1, "contrast": 1.1, "saturation": 1.2, "hue": 15, "zoomFactor": 1.05, "deviceMedia": "iPhone 16 Pro" } def process_video(): url = f"{BASE_URL}/api/v1/remix" headers = { "x-ty-api-key": API_KEY, "Content-Type": "application/json" } payload = { "video_url": VIDEO_URL, "parameters": parameters } print(f"Processing {VIDEO_URL}...") response = requests.post(url, headers=headers, json=payload) if response.status_code == 200: result = response.json() print("✅ Success!") print(f"Input URL: {result['data']['inputVideoUrl']}") if 'result' in result['data']: print(f"Result: {result['data']['result']}") return result else: print(f"❌ Error {response.status_code}: {response.text}") return None if __name__ == "__main__": result = process_video() if result: print(f"\nFull response:\n{json.dumps(result, indent=2)}") ``` ```javascript JavaScript theme={null} const fetch = require("node-fetch"); const API_KEY = "your-api-key-here"; const BASE_URL = "https://www.topyappers.com"; // Video URL from Cloudflare R2 or AWS S3 const VIDEO_URL = "https://my-bucket.s3.amazonaws.com/my-video.mp4"; // Optional parameters for video processing const parameters = { playbackSpeed: 1.2, brightness: 0.1, contrast: 1.1, saturation: 1.2, hue: 15, zoomFactor: 1.05, deviceMedia: "iPhone 16 Pro", }; async function processVideo() { const url = `${BASE_URL}/api/v1/remix`; const payload = { video_url: VIDEO_URL, parameters: parameters, }; try { const response = await fetch(url, { method: "POST", headers: { "x-ty-api-key": API_KEY, "Content-Type": "application/json", }, body: JSON.stringify(payload), }); const result = await response.json(); if (response.ok) { console.log("✅ Success!"); console.log(`Input URL: ${result.data.inputVideoUrl}`); if (result.data.result) { console.log(`Result: ${result.data.result}`); } return result; } else { console.error(`❌ Error ${response.status}: ${JSON.stringify(result)}`); return null; } } catch (error) { console.error(`❌ Error: ${error.message}`); return null; } } processVideo(); ``` ```typescript TypeScript theme={null} async function processVideo( videoUrl: string, parameters: object, apiKey: string, ): Promise { const baseUrl = "https://www.topyappers.com"; const response = await fetch(`${baseUrl}/api/v1/remix`, { method: "POST", headers: { "x-ty-api-key": apiKey, "Content-Type": "application/json", }, body: JSON.stringify({ video_url: videoUrl, parameters: parameters, }), }); if (!response.ok) { throw new Error(`API error: ${response.status}`); } return await response.json(); } // Usage with R2 URL const result = await processVideo( "https://pub-abc123.r2.dev/video.mp4", { playbackSpeed: 1.2, brightness: 0.1, deviceMedia: "iPhone 16 Pro" }, "YOUR_API_KEY", ); console.log("🎉 Processing complete:", result); ``` ```bash cURL theme={null} curl -X POST https://www.topyappers.com/api/v1/remix \ -H "x-ty-api-key: your-api-key-here" \ -H "Content-Type: application/json" \ -d '{ "video_url": "https://pub-abc123.r2.dev/video.mp4", "parameters": { "playbackSpeed": 1.2, "brightness": 0.1, "contrast": 1.1, "saturation": 1.2, "hue": 15, "zoomFactor": 1.05, "deviceMedia": "iPhone 16 Pro" } }' ``` ## React Example (Complete Component) ```tsx theme={null} import { useState } from "react"; export function VideoRemixProcessor() { const [videoUrl, setVideoUrl] = useState(""); const [result, setResult] = useState(null); const [loading, setLoading] = useState(false); const [error, setError] = useState(""); const handleSubmit = async (e: React.FormEvent) => { e.preventDefault(); if (!videoUrl) return; setLoading(true); setError(""); setResult(null); try { const response = await fetch("https://www.topyappers.com/api/v1/remix", { method: "POST", headers: { "Content-Type": "application/json", "x-ty-api-key": process.env.NEXT_PUBLIC_API_KEY!, }, body: JSON.stringify({ video_url: videoUrl, parameters: { playbackSpeed: 1.2, brightness: 0.1, contrast: 1.1, deviceMedia: "iPhone 16 Pro", }, }), }); if (!response.ok) { throw new Error(`API error: ${response.status}`); } const data = await response.json(); setResult(data); } catch (err) { setError(err.message); } finally { setLoading(false); } }; return (
setVideoUrl(e.target.value)} required />

Enter URL from Cloudflare R2 or AWS S3

{error && (

❌ Error: {error}

)} {result && (

✅ Complete!

{JSON.stringify(result, null, 2)}
)}
); } ``` ## Media URL Requirements Your media must be uploaded to cloud storage (Cloudflare R2, AWS S3, etc.) before processing. The URL must meet these requirements: * **Publicly Accessible**: The media URL must be publicly accessible (no authentication required) * **Cloud Storage**: Must be hosted on Cloudflare R2, AWS S3, or similar cloud storage * **Direct Links**: URL must point directly to the media file (not a webpage) * **Video Formats**: MP4, MOV, AVI, WebM * **Video Max File Size**: 150MB * **Image Formats**: JPG, PNG, WebP, GIF * **Image Batch Size**: Maximum 20 images per request ## Error Handling ### 400 Bad Request ```json theme={null} { "error": "Invalid media URL or parameters" } ``` ### 401 Unauthorized ```json theme={null} { "error": "Invalid API key" } ``` ### 429 Too Many Requests ```json theme={null} { "error": "Daily limit exceeded. Upgrade your plan or try in 24 hours.", "retryAfter": 86400, "limit": 100 } ``` ### 413 File Too Large ```json theme={null} { "error": "Video file too large. Maximum size is 150MB" } ``` ## Retry Logic Example ```typescript theme={null} async function processVideoWithRetry( videoUrl: string, parameters: object, apiKey: string, maxRetries = 3, ) { for (let i = 0; i < maxRetries; i++) { try { return await processVideo(videoUrl, parameters, apiKey); } catch (error) { if (i === maxRetries - 1) throw error; const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s await new Promise((resolve) => setTimeout(resolve, delay)); } } } ``` ## Best Practices 1. **Valid URLs**: Ensure media URLs are publicly accessible and point directly to media files 2. **File Size**: Keep video files under 150MB and image batches at 20 images or fewer 3. **File Formats**: Use supported formats for the media type you are processing 4. **Error Handling**: Always implement proper error handling for network and API errors 5. **Rate Limits**: Be mindful of rate limits and implement retry logic with exponential backoff 6. **API Keys**: Keep your API keys secure and never commit them to version control ## Rate Limits Please refer to the [Rate Limits](/rate-limits) documentation for information about API rate limits and best practices. # Get Songs Data Source: https://docs.topyappers.com/songs-api/endpoint/get GET /api/v1/songs Access trending songs data with various actions. Use the `action` parameter to specify what data to retrieve. # Overview Source: https://docs.topyappers.com/songs-api/overview Access trending songs data, rankings, and chart history # Songs API The Songs API provides access to trending songs data, chart rankings, and historical performance across different countries and time periods. ## Pricing Each API call costs **10 credits**, regardless of the action performed. ## Authentication All requests require an API key passed in the `x-ty-api-key` header. ```bash theme={null} curl "https://api.topyappers.com/api/v1/songs?action=countries" \ -H "x-ty-api-key: your-api-key" ``` ## Available Actions The Songs API uses an `action` parameter to determine what data to retrieve: | Action | Description | Required Parameters | | -------------- | ----------------------------------- | --------------------------- | | `countries` | Get list of available countries | None | | `weeks` | Get available weeks for a country | `country_code` | | `date-ranges` | Get available date ranges | None | | `rankings` | Get song rankings for a country | `country`, optional: `week` | | `global` | Get global song rankings | Optional: `week` | | `new-entries` | Get new chart entries for a country | `country` | | `search` | Search for songs | `q` | | `song-history` | Get historical data for a song | `song_id`, `country_code` | | `compare` | Compare rankings between two weeks | `country`, `week1`, `week2` | ## Action Examples ### Get Available Countries ```bash theme={null} curl "https://api.topyappers.com/api/v1/songs?action=countries" \ -H "x-ty-api-key: your-api-key" ``` ### Get Available Weeks ```bash theme={null} curl "https://api.topyappers.com/api/v1/songs?action=weeks&country_code=US" \ -H "x-ty-api-key: your-api-key" ``` ### Get Rankings for a Country ```bash theme={null} curl "https://api.topyappers.com/api/v1/songs?action=rankings&country=US&week=2026-W04" \ -H "x-ty-api-key: your-api-key" ``` ### Get Global Rankings ```bash theme={null} curl "https://api.topyappers.com/api/v1/songs?action=global&week=2026-W04" \ -H "x-ty-api-key: your-api-key" ``` ### Get New Chart Entries ```bash theme={null} curl "https://api.topyappers.com/api/v1/songs?action=new-entries&country=US" \ -H "x-ty-api-key: your-api-key" ``` ### Search Songs ```bash theme={null} curl "https://api.topyappers.com/api/v1/songs?action=search&q=trending" \ -H "x-ty-api-key: your-api-key" ``` ### Get Song History ```bash theme={null} curl "https://api.topyappers.com/api/v1/songs?action=song-history&song_id=123456&country_code=US" \ -H "x-ty-api-key: your-api-key" ``` ### Compare Two Weeks ```bash theme={null} curl "https://api.topyappers.com/api/v1/songs?action=compare&country=US&week1=2026-W03&week2=2026-W04" \ -H "x-ty-api-key: your-api-key" ``` ## Response Format All responses follow this structure: ```json theme={null} { "message": "OK", "action": "rankings", "credits_used": 10, "response": { // Action-specific data } } ``` ## Week Format Weeks are specified in ISO week format: `YYYY-Www` * `YYYY` - Four digit year * `W` - Literal "W" * `ww` - Two digit week number (01-53) Examples: * `2026-W01` - First week of 2026 * `2026-W04` - Fourth week of 2026 * `2025-W52` - Last week of 2025 ## Error Handling If required parameters are missing, you'll receive a helpful error response: ```json theme={null} { "error": "Missing required parameter: action", "available_actions": [ "countries", "weeks", "date-ranges", "rankings", "global", "new-entries", "search", "song-history", "compare" ], "example_usage": { "countries": "/api/v1/songs?action=countries", "weeks": "/api/v1/songs?action=weeks&country_code=US", "rankings": "/api/v1/songs?action=rankings&country=US&week=2026-W04", "global": "/api/v1/songs?action=global&week=2026-W04", "search": "/api/v1/songs?action=search&q=trending", "song_history": "/api/v1/songs?action=song-history&song_id=123&country_code=US", "compare": "/api/v1/songs?action=compare&country=US&week1=2026-W03&week2=2026-W04" } } ``` # Get Viral Posts Source: https://docs.topyappers.com/viral-content-api/endpoint/post POST /api/v1/viral-content Retrieve viral TikTok content filtered by categories, countries, views, virality and follower ranges, dates, music and hook, AI tag arrays and text-contains fields, and boolean content flags. See `ViralPostsRequest` in components/schemas. # Overview Source: https://docs.topyappers.com/viral-content-api/overview Discover viral TikTok content with powerful filtering options # Viral Content API The Viral Content API allows you to discover and analyze viral TikTok content. Filter by categories, countries, views, virality and follower ranges, dates, music and hook text, **AI-derived tags** (format, tone, look, setting, audience, production, CTA, emotion), **substring** fields on analyzed text, and **boolean content flags** (face visible, product, branded, and more). ## Key Features Filter viral posts by content categories like comedy, dance, food, and more. Find viral content from specific countries and regions. Filter by our proprietary virality score to find the most engaging content. Search for viral posts using specific trending sounds and music. ## Authentication All requests require an API key passed in the `x-ty-api-key` header. ```bash theme={null} curl -X POST https://api.topyappers.com/api/v1/viral-content \ -H "x-ty-api-key: your-api-key" \ -H "Content-Type: application/json" \ -d '{ "categories": ["Music"], "viewsMin": 100000, "page": 1, "pageSize": 12 }' ``` ## Request parameters All parameters are sent in the **JSON request body** (optional unless noted). Omit a field, use an empty array `[]`, or `null` where documented to apply no filter for that field. ### Core filters | Parameter | Type | Description | | ------------------ | --------- | -------------------------------------------------------------------------------------------------------------- | | `categories` | string\[] | Content categories. Values must match the **category enum** in OpenAPI (e.g. Arts, Fashion, Gaming, Music, …). | | `countries` | string\[] | Full **country names** as in OpenAPI (e.g. `United States`, `United Kingdom`). | | `viewsMin` | integer | Minimum view count (omit or `0` for no lower bound). | | `viewsMax` | integer | Maximum view count (omit or `0` for no upper bound). | | `viralityScoreMin` | float | Minimum virality score. | | `viralityScoreMax` | float | Maximum virality score. | | `followersMin` | integer | Minimum creator follower count. | | `followersMax` | integer | Maximum creator follower count. | | `dateCreatedFrom` | string | Post created on or after this date (`YYYY-MM-DD`). | | `dateCreatedTo` | string | Post created on or before this date (`YYYY-MM-DD`). | | `musicTitle` | string | Case-insensitive **partial** match on music/sound title. | | `hook` | string | Case-insensitive **partial** match on analyzed hook text. | ### AI analysis — tag arrays (OR within each field) For each array below, a post matches if its stored tag equals **any** value you send. Values are **fixed snake\_case strings**; see the linked schema in `openapi.json` for the complete enum per field. | Parameter | Type | OpenAPI schema (enum) | Maps to analyzed field | | --------------------- | --------- | --------------------- | --------------------------- | | `contentFormats` | string\[] | `ContentFormat` | `content_format` | | `contentTones` | string\[] | `ContentTone` | `content_tone` | | `visualStyles` | string\[] | `VisualStyle` | `visual_style` | | `videoSettings` | string\[] | `VideoSetting` | `setting` (filming setting) | | `targetDemographics` | string\[] | `TargetDemographic` | `target_demographic` | | `productionQualities` | string\[] | `ProductionQuality` | `production_quality` | | `ctaTypes` | string\[] | `CtaType` | `cta_type` | | `primaryEmotions` | string\[] | `PrimaryEmotion` | `primary_emotion` | ### AI analysis — text contains Case-insensitive substring match. Special regex characters in your string are treated **literally** (escaped server-side). | Parameter | Type | Description | | ------------------------- | ------ | ------------------------------------------------------ | | `videoTopicContains` | string | Substring match on `video_topic`. | | `contentCategoryContains` | string | Substring match on content niche / `content_category`. | | `productCategoryContains` | string | Substring match on `product_category`. | | `brandMentionedContains` | string | Substring match on `brand_mentioned`. | | `colorPaletteContains` | string | Substring match on `color_palette`. | ### Content flags (booleans) Omit the field for **no filter**. `true` / `false` restrict to posts that pass the corresponding analyzed signal. | Parameter | Type | Description | | ------------------ | ------- | -------------------------- | | `hasFace` | boolean | Visible face in the video. | | `hasProduct` | boolean | Product visible. | | `isBranded` | boolean | Branded / sponsored-style. | | `isPromotional` | boolean | Promotional. | | `hasTextOverlay` | boolean | On-screen text overlay. | | `isTrendingFormat` | boolean | Tagged as trending format. | | `isAiGenerated` | boolean | AI-generated look. | ### Pagination | Parameter | Type | Description | | ---------- | ------- | ------------------------------------------------- | | `page` | integer | Page number (default: `1`, minimum: `1`). | | `pageSize` | integer | Results per page (default: `12`, maximum: `100`). | ## Sorting The Viral Content API does **not** take `sortBy` / `sortOrder` in the request body. Results are **always returned in a fixed order**: * **Primary:** post **creation time** (`date_created` on the post), **newest first** (descending). So the first items on page 1 are the **most recently created** viral posts that match your filters. Use `dateCreatedFrom` / `dateCreatedTo` to narrow the time window; ordering within that window remains **newest first**. ## Pricing Each request costs **1 credit per returned content**. For example, if you request `pageSize: 12` and receive 12 results, that costs 12 credits. ## Rate Limits The Viral Content API is subject to rate limits. If you exceed the limit, you'll receive a `429` response with a `retryAfter` field indicating how long to wait before retrying.