# Core API Concepts

**Authentication**

Every request is authenticated by a Bearer credential in the `Authorization` header. There are two types of credential, each suited to a different use case:

- **[API Keys](/openapi/api-keys)** — call the API as yourself (scripts, backend services). Create and revoke them in the dashboard or via the API; you can hold several and revoke any one independently.
- **[OAuth](/openapi/oauth)** — for applications acting on behalf of other users (desktop or CLI tools), via OAuth 2.0 with PKCE.

Each credential carries one or more scopes that control what it can access. Today every credential is issued with full access; scoped, least-privilege credentials are planned.

**Discovery**

Identify and evaluate creators using structured, platform-specific search criteria.
Responses are intentionally constrained to support ranking, filtering, and selection
at scale rather than full profile hydration.

**Enrichment**

Retrieve complete creator-level data once a candidate has been identified.
Enrichment responses provide the depth required for analysis, activation,
and downstream data workflows.

**Execution modes**

Enrichment is available in both synchronous and asynchronous forms.
Single enrichment supports real-time use cases, while batch enrichment is optimized
for high-throughput, non-interactive processing.

**Typical usage**

Discovery and enrichment are designed as complementary stages.
Discovery narrows the candidate set; enrichment supplies detailed data
for creators that have already been qualified.


Version: 1.0.0

## Servers

Production
```
https://api-dashboard.influencers.club
```

## Security

### Bearer

Type: http
Scheme: bearer
Bearer Format: API_KEY

## Download OpenAPI description

 - [Core API Concepts](https://docs.influencers.club/_bundle/openapi.yaml)

## Discovery API

 - [POST /public/v1/discovery/](https://docs.influencers.club/openapi/discovery-api/public_v1_discovery_create.md): Search and discover creators across multiple platforms using advanced filtering and search. **What you get** - Paginated list of creator profiles with profile info, follower counts, engagement rates,
## Similar Creators

 - [POST /public/v1/discovery/creators/similar/](https://docs.influencers.club/openapi/similar-creators/public_v1_discovery_creators_similar_create.md): Discover creators similar to a reference creator based on various similarity criteria. **What you get** - Returns a paginated list of creator profiles that match the reference creator's characteristic
## Audience Overlap

 - [POST /public/v1/creators/audience/overlap/](https://docs.influencers.club/openapi/audience-overlap/public_v1_creators_audience_overlap_create.md): Compare audience overlap between 2-10 creators on a given platform. **What you get** - Returns per-creator audience overlap and unique audience percentages, plus report-level totals (total followers a
## Exclusion lists

 - [GET /public/v1/discovery/exclusion-lists/](https://docs.influencers.club/openapi/exclusion-lists/public_v1_discovery_exclusion_lists_list.md): Returns all exclusion lists available to your team, each scoped to a single platform. This includes both the auto-created default list per platform and any specific lists you have created. Adding hand
 - [POST /public/v1/discovery/exclusion-lists/](https://docs.influencers.club/openapi/exclusion-lists/public_v1_discovery_exclusion_lists_create.md): Creates a new specific exclusion list for the given platform and returns its `id`. Use specific lists for handles you want to apply selectively; for a standing, always-on blocklist use the platform's
 - [GET /public/v1/discovery/exclusion-lists/default/{platform}/](https://docs.influencers.club/openapi/exclusion-lists/public_v1_discovery_exclusion_lists_default_retrieve.md): Returns (and auto-creates if needed) the team's default exclusion list for the given platform. The default is your standing, always-on blocklist, addressed by platform rather than by ID, and cannot be
 - [GET /public/v1/discovery/exclusion-lists/default/{platform}/entries/](https://docs.influencers.club/openapi/exclusion-lists/public_v1_discovery_exclusion_lists_default_entries_retrieve.md): Returns a paginated list of handles in the platform's default exclusion list. Defaults to the first 1,000 handles; use `offset` and `limit` to page through larger lists. Handles are returned in alphab
 - [POST /public/v1/discovery/exclusion-lists/default/{platform}/entries/](https://docs.influencers.club/openapi/exclusion-lists/public_v1_discovery_exclusion_lists_default_entries_create.md): Appends handles to the platform's default exclusion list. Handles are normalised automatically (lowercased, @ stripped, full URLs reduced to just the handle). Adding handles does not filter search on
 - [DELETE /public/v1/discovery/exclusion-lists/default/{platform}/entries/](https://docs.influencers.club/openapi/exclusion-lists/public_v1_discovery_exclusion_lists_default_entries_delete.md): Removes handles from the platform's default exclusion list. Returns the updated list object. This operation is free — it does not consume credits.
 - [GET /public/v1/discovery/exclusion-lists/{list_id}/](https://docs.influencers.club/openapi/exclusion-lists/public_v1_discovery_exclusion_lists_retrieve.md): Returns a single specific exclusion list by ID.
 - [PATCH /public/v1/discovery/exclusion-lists/{list_id}/](https://docs.influencers.club/openapi/exclusion-lists/public_v1_discovery_exclusion_lists_partial_update.md): Updates the name of a specific exclusion list. Returns the updated list object. This operation is free — it does not consume credits.
 - [DELETE /public/v1/discovery/exclusion-lists/{list_id}/](https://docs.influencers.club/openapi/exclusion-lists/public_v1_discovery_exclusion_lists_delete.md): Permanently deletes a specific exclusion list and all its handles. The default list for a platform cannot be deleted. This operation is free — it does not consume credits.
 - [GET /public/v1/discovery/exclusion-lists/{list_id}/entries/](https://docs.influencers.club/openapi/exclusion-lists/public_v1_discovery_exclusion_lists_entries_retrieve.md): Returns a paginated list of handles in the specific exclusion list. Defaults to the first 1,000 handles; use `offset` and `limit` to page through larger lists. Handles are returned in alphabetical ord
 - [POST /public/v1/discovery/exclusion-lists/{list_id}/entries/](https://docs.influencers.club/openapi/exclusion-lists/public_v1_discovery_exclusion_lists_entries_create.md): Appends handles to the specific exclusion list. Handles are normalised automatically (lowercased, @ stripped, full URLs reduced to just the handle). Adding handles does not filter search on its own —
 - [DELETE /public/v1/discovery/exclusion-lists/{list_id}/entries/](https://docs.influencers.club/openapi/exclusion-lists/public_v1_discovery_exclusion_lists_entries_delete.md): Removes handles from the specific exclusion list. Returns the updated list object. This operation is free — it does not consume credits.
## Dictionary

 - [GET /public/v1/discovery/classifier/languages/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_languages_list.md): Retrieve a list of supported languages with their abbreviations for filtering creators by profile language or content language. Useful for discovering creators who create content in specific languages
 - [GET /public/v1/discovery/classifier/locations/{platform}/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_locations_retrieve.md): Retrieve a list of location identifiers available for a specific platform. **What you get** - Returns location strings that can be used to filter creators by geographic location in discovery searches.
 - [GET /public/v1/discovery/classifier/brands/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_brands_list.md): Returns brands that can be used in the `brands` filter on the Discovery API, to find creators who have worked with a brand or mentioned it in their content. Each entry has the brand's `username`, disp
 - [GET /public/v1/discovery/classifier/yt-topics/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_yt_topics_list.md): Retrieve a hierarchical list of YouTube topic categories and their subtopics. **What you get** - Returns YouTube topic categories and their subtopics. When using YouTube Discovery, pass `sub_topic_det
 - [GET /public/v1/discovery/classifier/games/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_games_list.md): Retrieve a list of video games available on Twitch that can be used for filtering creators. Returns game identifiers and metadata to help discover Twitch streamers who play specific games or have stre
 - [GET /public/v1/discovery/classifier/audience-brand-categories/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_audience_brand_categories_list.md): Returns a list of audience brand categories (e.g., Sports, Fashion, Technology) from Instagram creator audience data. Use these values in the audience.brand_categories filter on the Discovery API to s
 - [GET /public/v1/discovery/classifier/audience-brand-names/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_audience_brand_names_list.md): Returns a list of audience brand names (e.g., Nike, Apple, Starbucks) from Instagram creator audience data. Use these values in the audience.brands filter on the Discovery API to search for Instagram
 - [GET /public/v1/discovery/classifier/audience-interests/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_audience_interests_list.md): Returns a list of audience interest values from Instagram creator audience data. Use these values in the audience.interests filter on the Discovery API to search for Instagram creators (10k+ followers
 - [GET /public/v1/discovery/classifier/audience-locations/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_audience_locations_list.md): Returns a list of audience location values (countries, states, cities) from Instagram creator audience data. Use these values in the audience.location filter on the Discovery API to search for Instagr
## Connected Socials

 - [POST /public/v1/creators/socials/](https://docs.influencers.club/openapi/connected-socials/public_v1_creators_socials_create.md): Discover all verified social accounts connected to a creator, given a seed platform and handle. **What you get** - Returns an array of verified connected social accounts across platforms, including pl
## Enrich by handle full

 - [POST /public/v1/creators/enrich/handle/full/](https://docs.influencers.club/openapi/enrich-by-handle-full/public_v1_creators_enrich_handle_full_create.md): Perform comprehensive enrichment of a creator profile using their social media handle. **What you get** - Returns complete profile data including cross-platform presence, engagement analytics, followe
## Enrich by handle profile

 - [POST /public/v1/creators/enrich/handle/profile/](https://docs.influencers.club/openapi/enrich-by-handle-profile/public_v1_creators_enrich_handle_profile_create.md): Enrich a creator profile with identity, contact, and vetting data using their social media handle. **What you get** - Returns the identity/contact/vetting subset of the [Enrich by handle full](/openap
## Enrich by handle analytics

 - [POST /public/v1/creators/enrich/handle/analytics/](https://docs.influencers.club/openapi/enrich-by-handle-analytics/public_v1_creators_enrich_handle_analytics_create.md): Enrich a creator profile with performance analytics using their social media handle. **What you get** - Returns the performance-analytics subset of the [Enrich by handle full](/openapi/enrich-by-handl
## Enrich by handle raw

 - [POST /public/v1/creators/enrich/handle/raw/](https://docs.influencers.club/openapi/enrich-by-handle-raw/public_v1_creators_enrich_handle_raw_create.md): Retrieve raw platform data for a creator profile using their social media handle. **What you get** - Returns unprocessed platform-specific data directly from the source, including basic profile inform
## Enrich by email

 - [POST /public/v1/creators/enrich/email/](https://docs.influencers.club/openapi/enrich-by-email/public_v1_creators_enrich_email_create.md): Perform basic enrichment of creator profiles using an email address. **What you get** - Returns the creator's single strongest platform — the one with the highest follower count — with essential profi
## Batch enrichment

 - [POST /public/v1/enrichment/batch/](https://docs.influencers.club/openapi/batch-enrichment/public_v1_enrichment_batch_create.md): Create a batch enrichment job by uploading a CSV. **How it works** 1. Upload a `.csv` file (one column: `handle` or `email`) 2. Choose the enrichment mode (handle: `raw`/`full`, email: `basic`) 3. Use
 - [GET /public/v1/enrichment/batch/{batch_id}/status/](https://docs.influencers.club/openapi/batch-enrichment/public_v1_enrichment_batch_status_retrieve.md): Check the current processing status of a batch enrichment job. **What you get** - Current state (e.g., queued/running/completed/failed) - Progress indicators (processed vs remaining), when available
 - [POST /public/v1/enrichment/batch/{batch_id}/resume/](https://docs.influencers.club/openapi/batch-enrichment/public_v1_enrichment_batch_resume_create.md): Resume a paused or interrupted batch enrichment job. **When to use** - If a batch was paused or failed mid-run and needs to continue processing **Credits** - **0 credits** to resume (credits apply on
 - [GET /public/v1/enrichment/batch/{batch_id}/download/](https://docs.influencers.club/openapi/batch-enrichment/public_v1_enrichment_batch_download_retrieve.md): Download the enriched CSV dataset via a temporary presigned URL. **This is the recommended endpoint for downloading CSV results.** Compared to the direct download endpoint, this returns a short-lived
 - [GET /public/v1/enrichment/batch/{batch_id}/](https://docs.influencers.club/openapi/batch-enrichment/public_v1_enrichment_batch_retrieve.md): Download the final enriched dataset after processing is complete. > **Tip:** For CSV downloads, consider using the **recommended** endpoint `GET /public/v1/enrichment/batch/{batch_id}/download/` inste
## Subscriptions

 - [GET /public/v1/social/listening/subscription/](https://docs.influencers.club/openapi/subscriptions/public_v1_social_listening_subscription_list.md): Return a paginated list of the client's social-listening subscriptions, optionally filtered by type. The response includes a `summary` block with aggregate counts. Monitoring is billed per creator, pe
 - [POST /public/v1/social/listening/subscription/](https://docs.influencers.club/openapi/subscriptions/public_v1_social_listening_subscription_create.md): Create a new social-listening subscription from handles and/or discovery lists. Monitoring is billed per creator, per day — API calls are included in that price. See [Usage, pricing & limits](guides/u
 - [GET /public/v1/social/listening/subscription/{subscription_id}/](https://docs.influencers.club/openapi/subscriptions/public_v1_social_listening_subscription_retrieve.md): Return the full detail representation of a subscription, including creators, daily cost, and (for campaign subscriptions) stats. Monitoring is billed per creator, per day — API calls are included in t
 - [PATCH /public/v1/social/listening/subscription/{subscription_id}/](https://docs.influencers.club/openapi/subscriptions/public_v1_social_listening_subscription_partial_update.md): Partially update a subscription (name, endpoints, or creators). Status changes (pause/resume) on campaign-backed subscriptions are rejected; their lifecycle is driven by the campaign. Monitoring is bi
 - [DELETE /public/v1/social/listening/subscription/{subscription_id}/](https://docs.influencers.club/openapi/subscriptions/public_v1_social_listening_subscription_delete.md): Delete a webhook subscription and all its related links. Campaign-backed subscriptions are rejected; archive the campaign instead (`DELETE /campaign/<pk>/`). Monitoring is billed per creator, per day
 - [GET /public/v1/social/listening/subscription/{subscription_id}/creators/](https://docs.influencers.club/openapi/subscriptions/public_v1_social_listening_subscription_creators_retrieve.md): Return a paginated list of creators in the subscription with follower and source metadata, optionally filtered by handle via the `search` query parameter. Monitoring is billed per creator, per day — A
 - [POST /public/v1/social/listening/subscription/{subscription_id}/creators/](https://docs.influencers.club/openapi/subscriptions/public_v1_social_listening_subscription_creators_create.md): Add creators to the subscription from handles, discovery lists, and/or a CSV file (a `handle` column is required). Monitoring is billed per creator, per day — API calls are included in that price. See
 - [GET /public/v1/social/listening/subscription/{subscription_id}/details/](https://docs.influencers.club/openapi/subscriptions/public_v1_social_listening_subscription_details_retrieve.md): Return aggregated delivery stats for a campaign subscription. Monitoring is billed per creator, per day — API calls are included in that price. See [Usage, pricing & limits](guides/usage-limits.md#soc
 - [GET /public/v1/social/listening/subscription/{subscription_id}/details/export/](https://docs.influencers.club/openapi/subscriptions/public_v1_social_listening_subscription_details_export_retrieve.md): Download the campaign subscription's aggregated stats as a CSV file. Monitoring is billed per creator, per day — API calls are included in that price. See [Usage, pricing & limits](guides/usage-limits
## Campaigns

 - [GET /public/v1/social/listening/campaign/](https://docs.influencers.club/openapi/campaigns/public_v1_social_listening_campaign_list.md): Return a paginated list of the client's campaigns, optionally filtered by status and search, with a `status_counts` summary. Monitoring is billed per creator, per day — API calls are included in that
 - [POST /public/v1/social/listening/campaign/](https://docs.influencers.club/openapi/campaigns/public_v1_social_listening_campaign_create.md): Create a campaign and its backing per-platform webhook subscriptions. Monitoring is billed per creator, per day — API calls are included in that price. See [Usage, pricing & limits](guides/usage-limit
 - [GET /public/v1/social/listening/campaign/{campaign_id}/](https://docs.influencers.club/openapi/campaigns/public_v1_social_listening_campaign_retrieve.md): Return the detail representation of a single campaign by id. Team members can view campaigns within their client scope. Monitoring is billed per creator, per day — API calls are included in that price
 - [PATCH /public/v1/social/listening/campaign/{campaign_id}/](https://docs.influencers.club/openapi/campaigns/public_v1_social_listening_campaign_partial_update.md): Update a campaign's status, budget and/or content types. Setting `status` to `paused` or `active` pauses/resumes the campaign and cascades the same status to all its backing subscriptions; resuming ru
 - [DELETE /public/v1/social/listening/campaign/{campaign_id}/](https://docs.influencers.club/openapi/campaigns/public_v1_social_listening_campaign_delete.md): Archive a campaign and disable all its backing subscriptions. This is a soft delete: rows are retained but detection is stopped. Monitoring is billed per creator, per day — API calls are included in t
 - [GET /public/v1/social/listening/campaign/{campaign_id}/creators/](https://docs.influencers.club/openapi/campaigns/public_v1_social_listening_campaign_creators_retrieve.md): Return a paginated list of the campaign's creators with per-creator metrics (posts, views, engagement, ER%, EMV, and a 7-day trend), searchable by handle/name and sortable by any metric column. Creato
 - [POST /public/v1/social/listening/campaign/{campaign_id}/creators/](https://docs.influencers.club/openapi/campaigns/public_v1_social_listening_campaign_creators_create.md): Add creators to one of the campaign's platforms from handles, a discovery list, and/or a CSV file. Monitoring is billed per creator, per day — API calls are included in that price. See [Usage, pricing
 - [DELETE /public/v1/social/listening/campaign/{campaign_id}/creators/](https://docs.influencers.club/openapi/campaigns/public_v1_social_listening_campaign_creators_delete.md): Remove creators from the campaign by creator id (the `id` field from the Creators list). The creators' links are deleted while the campaign and subscriptions are kept; detection stops for the removed
 - [GET /public/v1/social/listening/campaign/{campaign_id}/overview/](https://docs.influencers.club/openapi/campaigns/public_v1_social_listening_campaign_overview_retrieve.md): Return the aggregated overview metrics for a single campaign, including total posts, views, engagement, EMV, and trends. Optionally filter by platform using the `platform` query parameter. Monitoring
 - [GET /public/v1/social/listening/campaign/{campaign_id}/content/](https://docs.influencers.club/openapi/campaigns/public_v1_social_listening_campaign_content_retrieve.md): Return a paginated feed of the campaign's posts (one per detected `new_post` event), optionally narrowed to a single platform and sorted by a metric column (defaults to most recent first). Each post c
 - [GET /public/v1/social/listening/campaign/{campaign_id}/report/](https://docs.influencers.club/openapi/campaigns/public_v1_social_listening_campaign_report_retrieve.md): Return the campaign's most recent AI report. While the report is being generated its `status` is `generating` and `report_data` is empty — poll until `status` becomes `ready` (or `failed`). Monitoring
 - [POST /public/v1/social/listening/campaign/{campaign_id}/report/](https://docs.influencers.club/openapi/campaigns/public_v1_social_listening_campaign_report_create.md): Start asynchronous generation of a new AI report for the campaign (also used to regenerate). Returns the pending report; poll the GET endpoint until its `status` is `ready`. If a generation is already
 - [GET /public/v1/social/listening/campaign/{campaign_id}/report/export/](https://docs.influencers.club/openapi/campaigns/public_v1_social_listening_campaign_report_export_retrieve.md): Download the campaign's raw post-level report data as a CSV file (one row per detected post with its metrics). Monitoring is billed per creator, per day — API calls are included in that price. See [Us
## Events

 - [GET /public/v1/social/listening/events/](https://docs.influencers.club/openapi/events/public_v1_social_listening_events_list.md): Return a paginated list of the client's events, optionally filtered by subscription, event type, or creator. Monitoring is billed per creator, per day — API calls are included in that price. See [Usag
 - [GET /public/v1/social/listening/events/{event_id}/](https://docs.influencers.club/openapi/events/public_v1_social_listening_events_retrieve.md): Return a single event with its full payload and delivery history. Monitoring is billed per creator, per day — API calls are included in that price. See [Usage, pricing & limits](guides/usage-limits.md
## Usage

 - [GET /public/v1/social/listening/usage/](https://docs.influencers.club/openapi/usage/public_v1_social_listening_usage_list.md): Return current social-listening limits and active subscription counts for the client's scope. Monitoring is billed per creator, per day — API calls are included in that price. See [Usage, pricing & li
## Creator Posts

 - [POST /public/v1/creators/content/posts/](https://docs.influencers.club/openapi/creator-posts/public_v1_creators_content_posts_create.md): Fetch recent posts for a creator on a given platform. **What you get** - Returns a list of recent posts with metadata including post ID, URL, caption, media URLs, timestamps, and engagement metrics (l
## Post Details

 - [POST /public/v1/creators/content/details/](https://docs.influencers.club/openapi/post-details/public_v1_creators_content_details_create.md): Retrieve detailed information about specific creator content. **What you get** - Supports Instagram, TikTok, and YouTube platforms. - Returns platform-specific content metadata and engagement data in
## Account credits & usage

 - [GET /public/v1/accounts/credits/](https://docs.influencers.club/openapi/account-credits-and-usage/account_credits_usage_retrieve.md): Use your API key to check your remaining credits and total credits used. **Response fields** - `credits_available` — remaining credits - `credits_used` — total credits consumed **Credits** - **0 cred
## API Keys

 - [GET /public/v1/accounts/tokens/](https://docs.influencers.club/openapi/api-keys/public_v1_accounts_tokens_list.md): Returns all API keys for the authenticated user, including inactive ones. Each response object includes the raw token value and the `active` field indicating current status.
 - [POST /public/v1/accounts/tokens/](https://docs.influencers.club/openapi/api-keys/public_v1_accounts_tokens_create.md): Creates a new API key. The token value is included in the response.
 - [PATCH /public/v1/accounts/tokens/{token_id}/](https://docs.influencers.club/openapi/api-keys/public_v1_accounts_tokens_partial_update.md): Update an API key's label, active status, expiration date, or scopes. Pass `null` for `expires_at` to remove expiration.
 - [DELETE /public/v1/accounts/tokens/{token_id}/](https://docs.influencers.club/openapi/api-keys/public_v1_accounts_tokens_delete.md)
## OAuth

 - [POST /public/v1/oauth/register/](https://docs.influencers.club/openapi/oauth/public_v1_oauth_register_create.md): Open endpoint — no authentication required. Desktop/CLI apps call this once to obtain a client_id they persist locally and reuse for all future authorize flows.
 - [GET /public/v1/oauth/authorize/](https://docs.influencers.club/openapi/oauth/public_v1_oauth_authorize_list.md): OAuth 2.1 authorization endpoint. The client opens the browser at this URL; valid requests are redirected to the frontend consent page where the user approves access.
 - [POST /public/v1/oauth/token/](https://docs.influencers.club/openapi/oauth/public_v1_oauth_token_create.md): Accepts `application/x-www-form-urlencoded` or `application/json`. **authorization_code grant:** `grant_type`, `code`, `code_verifier`, `client_id`, `redirect_uri` **refresh_token grant:** `grant_type
 - [GET /public/v1/oauth/apps/](https://docs.influencers.club/openapi/oauth/public_v1_oauth_apps_list.md): Returns all OAuth apps the authenticated user has authorized.
 - [DELETE /public/v1/oauth/apps/{app_id}/](https://docs.influencers.club/openapi/oauth/public_v1_oauth_apps_delete.md): Revokes the user's authorization for the given app and deactivates all associated access tokens.