{ "openapi": "3.1.0", "x-logo": { "url": "./images/vwd-logo.svg" }, "x-apiVersion": "1.0.0", "x-changelogUrl": "https://github.com/get-vwd/vwd-docs/releases", "info": { "title": "VwD External API", "description": "External API for accessing VwD creators data.", "version": "1.0.0", "contact": { "name": "VwD API Support", "email": "support@vwd.ai" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "servers": [ { "url": "https://api.vwd.ai/api/public/v1", "description": "VwD Production API Server" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Creators", "description": "Endpoints related to creators information and searches.", "x-displayName": "Creator Management" }, { "name": "Brands", "description": "Endpoints for brand search and management.", "x-displayName": "Brand Management" }, { "name": "Lists", "description": "Endpoints for managing creator lists.", "x-displayName": "List Management" }, { "name": "X-Ray", "description": "Endpoints for retrieving creators posts with labels.", "x-displayName": "Content Analysis" }, { "name": "X-Ray Brands", "description": "Endpoints for creators posts and timelines related to brands.", "x-displayName": "Brand Mentions" }, { "name": "X-Ray Compliance", "description": "Endpoints for creators compliance data.", "x-displayName": "Compliance Monitoring" }, { "name": "Search", "description": "Full-text search endpoints powered by Elasticsearch.", "x-displayName": "Search" } ], "x-tagGroups": [ { "name": "Core API", "tags": [ "Creators", "Brands", "Lists", "Search" ] }, { "name": "Content Analysis", "tags": [ "X-Ray", "X-Ray Brands", "X-Ray Compliance" ] } ], "paths": { "/creators/search/": { "post": { "summary": "Search and list creators", "description": "**Public API Endpoint**\n\nUse this endpoint to search creators based on various filters, with support for pagination and ordering.\nThis is a POST request and requires an API key for authentication.\n\nProvide filters to narrow down the search results. If no filters are provided, all creators are listed with pagination applied.\n", "operationId": "public_search_creators", "tags": [ "Creators" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Number of results per page.", "example": 10, "x-traitTag": true }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page number for pagination.", "example": 1, "x-traitTag": true }, { "name": "ordering", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "-created_at", "followers_reach", "-followers_reach" ] }, "description": "Ordering of results. Use a minus (`-`) prefix for descending order.", "example": "-created_at", "x-traitTag": true }, { "name": "include_child_scores", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "- true (default): return both top-level parent categories and child/leaf tags (zero-filled)\n- false: return parent category scores only (top-level categories)\n", "example": true, "x-traitTag": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "region": { "type": "string", "description": "Filter creators by their region.", "example": "europe" }, "gender": { "type": "string", "description": "Filter creators by gender.", "example": "male" }, "followers_reach": { "type": "integer", "description": "Minimum follower reach for filtering.", "example": 720000 }, "platform": { "type": "object", "description": "Platform filters (e.g., Instagram, Facebook).", "properties": { "instagram": { "type": "boolean", "example": true }, "facebook": { "type": "boolean", "example": false } } }, "content_alignment": { "type": "object", "description": "Content alignment filters for various types of content.", "properties": { "language_content": { "type": "integer", "example": 85 }, "sexual_content": { "type": "integer", "example": 85 }, "violence_content": { "type": "integer", "example": 86 }, "cyber_bully": { "type": "integer", "example": 84 }, "drug_content": { "type": "integer", "example": 84 }, "hate_content": { "type": "integer", "example": 82 }, "alcohol_content": { "type": "integer", "example": 83 }, "gambling_content": { "type": "integer", "example": 82 }, "politics_content": { "type": "integer", "example": 81 }, "religion_content": { "type": "integer", "example": 80 } } }, "brands": { "type": "array", "description": "Filter by associated brands.", "items": { "type": "string" }, "example": [] }, "creators_display_name": { "type": "string", "description": "Filter by the creator's display name (partial match allowed).", "example": "John" }, "is_filtered": { "type": "boolean", "description": "Whether to apply the filters or not.", "example": true } } } } } }, "responses": { "200": { "description": "A paginated list of creators matching the provided filters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "next": { "type": "string", "description": "URL for the next page of results.", "example": "https://api.vwd.ai/api/public/v1/creators/search/?limit=10&ordering=-created_at&page=2" }, "previous": { "type": "string", "description": "URL for the previous page of results.", "example": null }, "total_pages": { "type": "integer", "description": "Total number of pages available.", "example": 15 }, "total": { "type": "integer", "description": "Total number of creators matching the filters.", "example": 144 }, "creators": { "type": "array", "description": "A list of creators matching the filters.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique ID of the creators.", "example": 3975 }, "name": { "type": "string", "description": "Creator's name or brand.", "example": "BMW" }, "photo_url": { "type": "string", "description": "URL of the creator's profile picture.", "example": "https://media.qa.vwd.ai/media/creators-profile-pics/instagram_bmw.jpg" }, "region": { "type": "string", "description": "Region of the creators.", "example": "india" }, "gender": { "type": "string", "description": "Gender of the creators.", "example": "non_binary" }, "is_public": { "type": "boolean", "description": "Indicates whether the creators is public or private.", "example": false }, "followers_reach": { "type": "integer", "description": "Total number of followers reached by the creators.", "example": 40337817 }, "follower_reach_normalised": { "type": "string", "description": "Normalized follower reach.", "example": "40.3 m" }, "pronoun": { "type": "string", "description": "Pronoun of the creators.", "example": "" }, "age": { "type": "integer", "description": "Age of the creators.", "example": 34 }, "social_profiles": { "type": "array", "description": "List of creator's social profiles.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Social profile ID.", "example": 4189 }, "profile_url": { "type": "string", "description": "URL of the social profile.", "example": "https://www.instagram.com/ttt" }, "platform": { "type": "string", "description": "Platform name (e.g., Instagram, Facebook).", "example": "instagram" }, "social_handle": { "type": "string", "description": "Handle of the social profile.", "example": "ttt" } } } }, "scores": { "type": "object", "description": "Scores across various compliance and risk categories.", "additionalProperties": { "type": "object", "properties": { "value": { "type": "number", "example": 1.38 } } } }, "summary": { "type": "string", "description": "Summary of the creator's profile.", "example": "BMW is a non-binary creators based in India, active on Instagram." }, "avg_comments_per_post": { "type": "string", "description": "Average comments per post.", "example": "494 " }, "avg_likes_per_post": { "type": "string", "description": "Average likes per post.", "example": "108.2 k" }, "avg_views_per_video": { "type": "string", "description": "Average views per video.", "example": "60.4 k" }, "total_compliance_violations": { "type": "integer", "description": "Total compliance violations by the creators.", "example": 86 }, "is_monitored": { "type": "boolean", "description": "Indicates whether the creator is currently being monitored (actively scanned for new content).", "example": true }, "brands": { "type": "array", "description": "List of associated brands", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Brand ID", "example": 1 }, "name": { "type": "string", "description": "Brand name (lowercased)", "example": "nike" } } } } } } } } } } } }, "400": { "description": "Bad Request - Invalid input data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Invalid input data." } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Authentication credentials were not provided." } } } } } }, "403": { "description": "Forbidden - API key does not have access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "You do not have permission to perform this action." } } } } } } } } }, "/creators/{id}/": { "get": { "summary": "Retrieve an creator's profile", "description": "**Public API Endpoint**\n\nUse this endpoint to retrieve an creator's profile. Only accessible if the API key is valid and the creators\nbelongs to the organization associated with the API key.\n", "operationId": "public_retrieve_creators_profile", "tags": [ "Creators" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the creators to retrieve.", "schema": { "type": "integer" }, "example": 12345 }, { "name": "include_child_scores", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "- true (default): return both top-level parent categories and child/leaf tags (zero-filled)\n- false: return parent category scores only (top-level categories)\n", "example": true, "x-traitTag": true } ], "responses": { "200": { "description": "Successfully retrieved the creators profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatorWithBrands" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Creators not found or not accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/creators/{id}/posts/": { "get": { "summary": "Retrieve Creators Posts with Labels", "description": "**Public API Endpoint**\n\nFetch all posts for a specific creators tagged with the specified media category.\nOptional year and month parameters can be used to filter posts by date.\nRequires an API key for authentication.\n", "operationId": "public_get_posts_with_labels", "tags": [ "X-Ray" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the creators whose posts are being retrieved.", "required": true, "schema": { "type": "integer" } }, { "name": "year", "in": "query", "description": "Year for filtering posts (optional).", "required": false, "schema": { "type": "integer" }, "x-traitTag": true }, { "name": "month", "in": "query", "description": "Month for filtering posts (optional).", "required": false, "schema": { "type": "integer" }, "x-traitTag": true }, { "name": "media_category", "in": "query", "description": "Top-level content category for filtering posts. Child subcategories are also accepted.\n", "required": true, "schema": { "type": "string", "enum": [ "sexual_content", "violence_content", "drug_content", "alcohol_content", "cyber_bully", "gambling_content", "hate_content", "language_content", "politics_content", "religion_content" ] }, "x-traitTag": true } ], "responses": { "200": { "description": "A list of posts with labels.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Post ID.", "example": 12345 }, "platform_name": { "type": "string", "description": "Platform name.", "example": "Instagram" }, "date": { "type": "string", "description": "Date of the post.", "example": "January 1, 2024" }, "link": { "type": "string", "description": "Link to the post.", "example": "https://instagram.com/post/12345" }, "score": { "type": "number", "format": "float", "description": "Normalized confidence score of the post.", "example": 95.5 }, "reasons": { "type": "array", "description": "Content analysis reasons for the post, grouped by category.", "items": { "type": "object", "properties": { "reason": { "type": "string", "description": "Description of why the content was flagged.", "example": "Image contains alcoholic beverages." }, "category": { "type": "string", "description": "Top-level content category.", "example": "alcohol_content" }, "subcategory": { "type": [ "string", "null" ], "description": "Specific child category, or null if the flag is at the top level.", "example": "alcoholic_beverages" }, "score": { "type": "number", "description": "Confidence score for this reason.", "example": 0.95 }, "source_type": { "type": "string", "description": "Type of content source (image, video, text, or transcription).", "example": "image" }, "timestamps": { "type": "array", "description": "Timestamps in seconds where the content was detected (video only).", "items": { "type": "number" }, "example": [] }, "text_preview": { "type": "string", "description": "Text content associated with the detection (included for text/transcription sources)." } } } }, "brands": { "type": "array", "description": "Brands mentioned in the post.", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "nike" } } } }, "is_dismissed": { "type": "boolean", "description": "Whether the post has been dismissed.", "example": false }, "article_title": { "type": "string", "description": "Article title (Google News posts only)." }, "image_url": { "type": "string", "description": "Image URL (Google News posts only)." }, "article_text": { "type": "string", "description": "Article text content (Google News and Reddit posts only)." }, "source_name": { "type": "string", "description": "Source name (Google News posts only)." } } } } } } }, "400": { "description": "Invalid media category provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/creators/{id}/posts/{post_id}/brands/": { "get": { "summary": "Retrieve All Brands for a Specific Post", "description": "**Public API Endpoint**\n\nFetch all brands mentioned in a specific post for a given creators.\nReturns brands sorted by mention count in descending order.\nRequires an API key for authentication.\n", "operationId": "public_get_post_brand_details", "tags": [ "X-Ray Brands" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the creators.", "required": true, "schema": { "type": "integer" } }, { "name": "post_id", "in": "path", "description": "ID of the post.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of all brands mentioned in the post.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Brand ID.", "example": 1 }, "name": { "type": "string", "description": "Brand name.", "example": "nike" }, "count": { "type": "integer", "description": "Number of times the brand is mentioned in the post.", "example": 3 } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Post or creators not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/creators/{id}/timeline/": { "get": { "summary": "Retrieve creators Timeline by Media Category", "description": "**Public API Endpoint**\n\nFetch a timeline of posts for a given creators based on the specified media category.\nThe response groups posts by year and month.\nRequires an API key for authentication.\n", "operationId": "public_get_creators_timeline", "tags": [ "X-Ray" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the creators.", "required": true, "schema": { "type": "integer" } }, { "name": "media_category", "in": "query", "description": "Top-level content category for filtering posts. Child subcategories are also accepted.\n", "required": true, "schema": { "type": "string", "enum": [ "sexual_content", "violence_content", "drug_content", "alcohol_content", "cyber_bully", "gambling_content", "hate_content", "language_content", "politics_content", "religion_content" ] }, "x-traitTag": true } ], "responses": { "200": { "description": "Timeline of posts grouped by year and month.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer", "description": "Year of the timeline.", "example": 2024 }, "months": { "type": "array", "description": "List of months with active status.", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Month name.", "example": "January" }, "active": { "type": "boolean", "description": "Indicates if posts exist for the month.", "example": true }, "month": { "type": "integer", "description": "Numeric representation of the month.", "example": 1 } } } } } } } } } }, "400": { "description": "Invalid media category provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/creators/{id}/brands-timeline/": { "get": { "summary": "Retrieve Creators Brand Timeline", "description": "**Public API Endpoint**\n\nFetch a timeline of posts for a given creators mentioning one or more brands.\nThe timeline groups posts by year and month.\nRequires an API key for authentication.\n", "operationId": "public_get_brand_timeline_for_creators", "tags": [ "X-Ray Brands" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the creators.", "required": true, "schema": { "type": "integer" } }, { "name": "brand_ids", "in": "query", "description": "Comma-separated brand IDs (e.g., 123,456,789).", "required": true, "schema": { "type": "string" }, "x-traitTag": true } ], "responses": { "200": { "description": "Timeline of posts mentioning the brands, grouped by year and month.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer", "description": "Year of the timeline.", "example": 2024 }, "months": { "type": "array", "description": "List of months with active status.", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Month name.", "example": "January" }, "active": { "type": "boolean", "description": "Indicates if posts exist for the month.", "example": true }, "month": { "type": "integer", "description": "Numeric representation of the month.", "example": 1 } } } } } } } } } }, "400": { "description": "Missing or invalid brand IDs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/creators/{id}/brands-posts/": { "get": { "summary": "Retrieve Creators Brand Posts", "description": "**Public API Endpoint**\n\nFetch all posts for a specific creators mentioning one or more brands.\nEach post includes associated brands information with id, name, and count.\nOptional filters for year and month can be applied.\nRequires an API key for authentication.\n", "operationId": "public_get_brand_posts", "tags": [ "X-Ray Brands" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the creators.", "required": true, "schema": { "type": "integer" } }, { "name": "brand_ids", "in": "query", "description": "Comma-separated brand IDs (e.g., 123,456,789).", "required": true, "schema": { "type": "string" }, "x-traitTag": true }, { "name": "year", "in": "query", "description": "Year filter for posts (optional).", "required": false, "schema": { "type": "integer" }, "x-traitTag": true }, { "name": "month", "in": "query", "description": "Month filter for posts (optional).", "required": false, "schema": { "type": "integer" }, "x-traitTag": true } ], "responses": { "200": { "description": "List of posts mentioning the brands, with details and associated brands data.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Post ID.", "example": 12345 }, "platform_name": { "type": "string", "description": "Platform name where the post was published.", "example": "Instagram" }, "date": { "type": "string", "description": "Date of the post.", "example": "January 1, 2024" }, "link": { "type": "string", "description": "URL link to the post.", "example": "https://instagram.com/post/12345" }, "score": { "type": "number", "format": "float", "description": "Normalized confidence score of the post.", "example": 95.5 }, "reasons": { "type": "array", "description": "Brand mention reasons for the post.", "items": { "type": "object", "properties": { "reason": { "type": "string", "description": "Description of the brand mention.", "example": "Brand logo visible in image." }, "category": { "type": "string", "description": "Brand name.", "example": "nike" }, "subcategory": { "type": [ "string", "null" ], "description": "Subcategory (null for brand mentions).", "example": null }, "score": { "type": "number", "description": "Confidence score for this detection.", "example": 0.92 }, "source_type": { "type": "string", "description": "Type of content source (image, video, text, or transcription).", "example": "image" }, "timestamps": { "type": "array", "description": "Timestamps in seconds where the brand was detected (video only).", "items": { "type": "number" }, "example": [] }, "text_preview": { "type": "string", "description": "Text content associated with the detection (included for text/transcription sources)." } } } }, "brands": { "type": "array", "description": "Brands mentioned in the post with mention counts.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Brand ID.", "example": 1 }, "name": { "type": "string", "description": "Brand name.", "example": "nike" }, "count": { "type": "integer", "description": "Number of mentions.", "example": 3 } } } }, "is_dismissed": { "type": "boolean", "description": "Whether the post has been dismissed.", "example": false }, "article_title": { "type": "string", "description": "Article title (Google News posts only)." }, "image_url": { "type": "string", "description": "Image URL (Google News posts only)." }, "article_text": { "type": "string", "description": "Article text content (Google News and Reddit posts only)." }, "source_name": { "type": "string", "description": "Source name (Google News posts only)." } } } } } } }, "204": { "description": "No posts found for the specified parameters." }, "400": { "description": "Missing or invalid parameters (e.g., creators ID or brand IDs).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/creators/{id}/compliance-timeline/": { "get": { "summary": "Retrieve Creators Compliance Timeline", "description": "**Public API Endpoint**\n\nFetch a timeline of compliance violations for a given creators.\nThe response groups compliance violations by year and month.\nRequires an API key for authentication.\n", "operationId": "public_get_compliance_timeline_for_creators", "tags": [ "X-Ray Compliance" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the creators.", "required": true, "schema": { "type": "integer" } }, { "name": "compliance_key", "in": "query", "description": "Compliance framework or specific violation subcategory to filter by.\n\n**Top-level frameworks:** FTC, FINRA, Healthcare\n\n**FTC subcategories:** FTC_PARTNERSHIP, FTC_FALSE_CLAIMS, FTC_FALSE_ADVICE, FTC_COPPA, FTC_PRIVACY\n\n**FINRA subcategories:** FINRA_FALSE_CLAIMS, FINRA_FALSE_STATEMENTS, FINRA_FALSE_ADVICE, FINRA_COMPARATIVE_STATEMENTS, FINRA_MEMBERSHIP, FINRA_FIGURES\n\n**Healthcare subcategories:** HEALTHCARE_PERSONAL_INFORMATION, HEALTHCARE_FALSE_INFORMATION, HEALTHCARE_PRODUCT_USE, HEALTHCARE_CLINICAL_INACCURACY, HEALTHCARE_NON_ACCESSIBLE_CONTENT, HEALTHCARE_INFORMATION_LIMITATIONS\n", "required": true, "schema": { "type": "string", "enum": [ "FTC", "FINRA", "Healthcare", "FTC_PARTNERSHIP", "FTC_FALSE_CLAIMS", "FTC_FALSE_ADVICE", "FTC_COPPA", "FTC_PRIVACY", "FINRA_FALSE_CLAIMS", "FINRA_FALSE_STATEMENTS", "FINRA_FALSE_ADVICE", "FINRA_COMPARATIVE_STATEMENTS", "FINRA_MEMBERSHIP", "FINRA_FIGURES", "HEALTHCARE_PERSONAL_INFORMATION", "HEALTHCARE_FALSE_INFORMATION", "HEALTHCARE_PRODUCT_USE", "HEALTHCARE_CLINICAL_INACCURACY", "HEALTHCARE_NON_ACCESSIBLE_CONTENT", "HEALTHCARE_INFORMATION_LIMITATIONS" ] }, "x-traitTag": true } ], "responses": { "200": { "description": "Timeline of compliance violations grouped by year and month.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer", "description": "Year of the timeline.", "example": 2024 }, "months": { "type": "array", "description": "List of months with active status.", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Month name.", "example": "January" }, "active": { "type": "boolean", "description": "Indicates if violations exist for the month.", "example": true }, "month": { "type": "integer", "description": "Numeric representation of the month.", "example": 1 } } } } } } } } } }, "400": { "description": "Missing or invalid compliance key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/creators/{id}/compliance-posts/": { "get": { "summary": "Retrieve Creators Compliance Posts", "description": "**Public API Endpoint**\n\nFetch all posts for a given creators with compliance violations.\nOptional filters for year and month can be applied.\nRequires an API key for authentication.\n", "operationId": "public_get_compliance_posts", "tags": [ "X-Ray Compliance" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the creators.", "required": true, "schema": { "type": "integer" } }, { "name": "compliance_key", "in": "query", "description": "Compliance framework or specific violation subcategory to filter by.\n\n**Top-level frameworks:** FTC, FINRA, Healthcare\n\n**FTC subcategories:** FTC_PARTNERSHIP, FTC_FALSE_CLAIMS, FTC_FALSE_ADVICE, FTC_COPPA, FTC_PRIVACY\n\n**FINRA subcategories:** FINRA_FALSE_CLAIMS, FINRA_FALSE_STATEMENTS, FINRA_FALSE_ADVICE, FINRA_COMPARATIVE_STATEMENTS, FINRA_MEMBERSHIP, FINRA_FIGURES\n\n**Healthcare subcategories:** HEALTHCARE_PERSONAL_INFORMATION, HEALTHCARE_FALSE_INFORMATION, HEALTHCARE_PRODUCT_USE, HEALTHCARE_CLINICAL_INACCURACY, HEALTHCARE_NON_ACCESSIBLE_CONTENT, HEALTHCARE_INFORMATION_LIMITATIONS\n", "required": true, "schema": { "type": "string", "enum": [ "FTC", "FINRA", "Healthcare", "FTC_PARTNERSHIP", "FTC_FALSE_CLAIMS", "FTC_FALSE_ADVICE", "FTC_COPPA", "FTC_PRIVACY", "FINRA_FALSE_CLAIMS", "FINRA_FALSE_STATEMENTS", "FINRA_FALSE_ADVICE", "FINRA_COMPARATIVE_STATEMENTS", "FINRA_MEMBERSHIP", "FINRA_FIGURES", "HEALTHCARE_PERSONAL_INFORMATION", "HEALTHCARE_FALSE_INFORMATION", "HEALTHCARE_PRODUCT_USE", "HEALTHCARE_CLINICAL_INACCURACY", "HEALTHCARE_NON_ACCESSIBLE_CONTENT", "HEALTHCARE_INFORMATION_LIMITATIONS" ] }, "x-traitTag": true }, { "name": "year", "in": "query", "description": "Year filter for posts (optional).", "required": false, "schema": { "type": "integer" }, "x-traitTag": true }, { "name": "month", "in": "query", "description": "Month filter for posts (optional).", "required": false, "schema": { "type": "integer" }, "x-traitTag": true } ], "responses": { "200": { "description": "List of posts with compliance violations.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Post ID.", "example": 12345 }, "platform_name": { "type": "string", "description": "Platform name where the post was published.", "example": "Instagram" }, "date": { "type": "string", "description": "Date of the post.", "example": "January 1, 2024" }, "link": { "type": "string", "description": "URL link to the post.", "example": "https://instagram.com/post/12345" }, "reasons": { "type": "array", "description": "List of compliance violation reasons associated with the post.", "items": { "type": "object", "properties": { "reason": { "type": "string", "description": "Description of the compliance violation.", "example": "Post promotes a product without disclosing the paid partnership." }, "category": { "type": "string", "description": "Top-level compliance framework (FTC, FINRA, or Healthcare).", "example": "FTC" }, "subcategory": { "type": "string", "description": "Specific violation type key.", "example": "FTC_PARTNERSHIP" }, "text_preview": { "type": "string", "description": "Text content associated with the violation (included when available)." } } } }, "brands": { "type": "array", "description": "Brands mentioned in the post.", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "nike" } } } }, "is_dismissed": { "type": "boolean", "description": "Whether the post has been dismissed.", "example": false }, "article_title": { "type": "string", "description": "Article title (Google News posts only)." }, "image_url": { "type": "string", "description": "Image URL (Google News posts only)." }, "article_text": { "type": "string", "description": "Article text content (Google News and Reddit posts only)." }, "source_name": { "type": "string", "description": "Source name (Google News posts only)." } } } } } } }, "204": { "description": "No posts found for the specified parameters." }, "400": { "description": "Missing or invalid parameters (e.g., creators ID or compliance key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/brands/": { "get": { "summary": "Find brand by name", "description": "**Public API Endpoint**\n\nFind brand by name (case-insensitive exact match). Returns an array with 0 or 1 item, each with id and name.\n", "operationId": "public_get_brands", "tags": [ "Brands" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "name", "in": "query", "required": false, "description": "Case-insensitive brand name to match exactly. If omitted or blank, returns an empty list.", "schema": { "type": "string" }, "example": "NIKE", "x-traitTag": true } ], "responses": { "200": { "description": "Successfully retrieved brands matching the name.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Brand ID", "example": 1 }, "name": { "type": "string", "description": "Brand name (stored normalized to lowercase)", "example": "nike" } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/creators/": { "get": { "summary": "List all creators", "description": "**Public API Endpoint**\n\nList creators for the authenticated organization with pagination. Response items include associated brands with IDs.\n", "operationId": "public_list_creators", "tags": [ "Creators" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page number for pagination.", "example": 1, "x-traitTag": true }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Number of results per page.", "example": 10, "x-traitTag": true }, { "name": "include_child_scores", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "- false (default): return parent category scores only (top-level categories)\n- true: return both top-level parent categories and child/leaf tags (zero-filled)\n", "example": false, "x-traitTag": true } ], "responses": { "200": { "description": "Successfully retrieved creators list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "creators": { "type": "array", "items": { "$ref": "#/components/schemas/CreatorWithBrands" } }, "total": { "type": "integer", "description": "Total number of creators", "example": 100 }, "count": { "type": "integer", "description": "Number of creators in current page", "example": 10 }, "next": { "type": [ "string", "null" ], "description": "URL for next page", "example": "https://api.vwd.ai/api/public/v1/creators/?page=2&limit=10" } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "summary": "Add creators", "description": "**Public API Endpoint**\n\nAdd creators either one at a time (single JSON object) or in bulk (object with items array).\nEnforces organization quotas (creation caps); supports partial success in bulk.\nDetects duplicates and optionally requires confirmation.\n", "operationId": "public_create_creators", "tags": [ "Creators" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SingleCreatorRequest" }, { "$ref": "#/components/schemas/BulkCreatorRequest" } ] }, "examples": { "single": { "summary": "Add single creator", "value": { "name": "Jane Doe", "social_profiles": [ { "platform": "instagram", "profile_url": "https://instagram.com/janedoe" } ], "confirm_duplicate": false } }, "bulk": { "summary": "Add multiple creators", "value": { "confirm_duplicates": false, "items": [ { "name": "Creator A", "social_profiles": [ { "platform": "instagram", "profile_url": "https://instagram.com/a" } ] }, { "name": "Creator B", "social_profiles": [ { "platform": "instagram", "profile_url": "https://instagram.com/b" } ] } ] } } } } } }, "responses": { "200": { "description": "Bulk creators request processed (partial success allowed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCreatorResponse" } } } }, "201": { "description": "Single creator created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatorCreatedResponse" } } } }, "400": { "description": "Bad Request - Invalid input data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "social_profiles": [ "At least one valid social profile is required." ] } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaExceeded" } } } }, "409": { "description": "Duplicate detected - requires confirmation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateDetected" } } } } } } }, "/creators/{id}/monitor/": { "post": { "summary": "Enable creator monitoring", "description": "**Public API Endpoint**\n\nEnables monitoring for an existing creator in your organization.\nIdempotent: calling again when already enabled still returns is_monitored: true.\nEnforces organization monitoring quotas (caps).\n", "operationId": "public_monitor_creator", "tags": [ "Creators" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Creator ID to enable monitoring for", "schema": { "type": "integer" }, "example": 123 } ], "responses": { "200": { "description": "Monitoring enabled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "is_monitored": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaExceeded" } } } }, "404": { "description": "Creator not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Creator not found" } } } } } } } } }, "/lists/": { "get": { "summary": "List creator lists", "description": "**Public API Endpoint**\n\nList creator lists for the organization (API key). Supports pagination via page and limit query params.\n", "operationId": "public_list_lists", "tags": [ "Lists" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page number for pagination.", "example": 1, "x-traitTag": true }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Number of results per page.", "example": 10, "x-traitTag": true } ], "responses": { "200": { "description": "Successfully retrieved lists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "lists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "List ID", "example": "00000000-0000-0000-0000-000000000000" }, "name": { "type": "string", "description": "List name", "example": "List A" }, "influencers_count": { "type": "integer", "description": "Number of influencers in the list", "example": 2 } } } }, "total": { "type": "integer", "description": "Total number of lists", "example": 10 }, "count": { "type": "integer", "description": "Number of lists in current page", "example": 2 }, "next": { "type": [ "string", "null" ], "description": "URL for next page", "example": null } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/lists/{id}/": { "get": { "summary": "Get list details", "description": "**Public API Endpoint**\n\nRetrieve a single list with metadata and a paginated preview of its creators.\n", "operationId": "public_get_list", "tags": [ "Lists" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "List ID (UUID)", "schema": { "type": "string", "format": "uuid" }, "example": "00000000-0000-0000-0000-000000000000" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page number for pagination.", "example": 1, "x-traitTag": true }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Number of results per page.", "example": 10, "x-traitTag": true }, { "name": "include_child_scores", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "- true (default): return both top-level parent categories and child/leaf tags (zero-filled)\n- false: return parent category scores only (top-level categories)\n", "example": true, "x-traitTag": true } ], "responses": { "200": { "description": "Successfully retrieved list details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "name": { "type": "string", "example": "List A" }, "influencers_count": { "type": "integer", "example": 5 }, "creators": { "type": "array", "items": { "$ref": "#/components/schemas/CreatorWithBrands" } }, "total": { "type": "integer", "description": "Total number of creators in the list", "example": 5 }, "count": { "type": "integer", "description": "Number of creators in current page", "example": 2 }, "next": { "type": [ "string", "null" ], "description": "URL for next page", "example": "/api/public/v1/lists/000.../?page=2&limit=2" } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/lists/{id}/creators/": { "post": { "summary": "Add creators to list", "description": "**Public API Endpoint**\n\nAdd existing creators (by id) to a list. Idempotent: adding the same creator again returns it under already_present.\n", "operationId": "public_add_creators_to_list", "tags": [ "Lists" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "List ID (UUID)", "schema": { "type": "string", "format": "uuid" }, "example": "00000000-0000-0000-0000-000000000000" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "influencer_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of creator IDs to add to the list", "example": [ 1, 2, 3 ] } }, "required": [ "influencer_ids" ] } } } }, "responses": { "200": { "description": "Creators added to list successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "added_influencers": { "type": "array", "items": { "type": "integer" }, "description": "IDs of creators successfully added", "example": [ 1, 2 ] }, "already_present": { "type": "array", "items": { "type": "integer" }, "description": "IDs of creators already in the list", "example": [ 2 ] }, "not_found_influencers": { "type": "array", "items": { "type": "integer" }, "description": "IDs of creators not found or not accessible", "example": [ 999 ] } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/search/creators/": { "post": { "summary": "Search creators by content", "description": "Full-text search across creator names, summaries, and associated post content powered by Elasticsearch.\nSupports boolean keyword logic (AND/OR/NOT), exact phrase matching, platform filtering,\nlist filtering, and multiple sort options.\n\nResults are automatically scoped to the organization associated with the API key.\n", "operationId": "public_search_creators_es", "tags": [ "Search" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "q" ], "properties": { "q": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Free-text search query matched against the creator's name, summary,\nand associated post content. Maximum 500 characters.\n", "example": "sustainable fashion" }, "exact": { "type": "boolean", "default": false, "description": "When true the query is treated as an exact phrase — the words must appear\nconsecutively and in the given order. When false (default) the query is\ntokenised and matched with partial/fuzzy logic.\n", "example": false }, "must_include_all": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 10, "description": "AND logic — every keyword in this list must be present in the matching post content. Maximum 10 items, each up to 200 characters.", "example": [ "vegan", "organic" ] }, "must_not_include": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 10, "description": "NOT logic — none of the keywords in this list should appear in the matching post content. Maximum 10 items, each up to 200 characters.", "example": [ "spam" ] }, "may_include_any": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 10, "description": "OR logic — at least one keyword from this list must be present in the matching post content. Maximum 10 items, each up to 200 characters.", "example": [ "eco-friendly", "green" ] }, "sort_by": { "type": "string", "enum": [ "relevance", "followers_reach", "name", "avg_likes_per_post", "avg_views_per_video", "avg_comments_per_post", "total_compliance_violations", "created_at", "posts_count", "-followers_reach", "-name", "-avg_likes_per_post", "-avg_views_per_video", "-avg_comments_per_post", "-total_compliance_violations", "-created_at", "-posts_count" ], "default": "relevance", "description": "Sort order for results. Use `relevance` (default) to rank by search score.\nPrefix a field name with `-` for descending order.\n", "example": "-followers_reach" }, "page": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1, "description": "1-based page number (1–100). Defaults to 1.", "example": 1 }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Number of results per page (1–100). Defaults to 10.", "example": 10 }, "filters": { "type": "object", "description": "Optional nested object with platform, creator, and list filters.", "properties": { "platforms": { "type": "array", "items": { "type": "string", "enum": [ "instagram", "facebook", "youtube", "tiktok", "twitter", "google_news", "reddit" ] }, "description": "Filter results to specific platforms.", "example": [ "instagram", "tiktok" ] }, "influencer_id": { "type": "integer", "description": "Filter results to a single creator by their numeric ID.", "example": 12345 }, "list_id": { "type": "string", "format": "uuid", "description": "Filter results to creators that belong to a specific creator list (UUID).", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } } } }, "responses": { "200": { "description": "Successfully retrieved search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatorSearchResponse" } } } }, "400": { "description": "Bad Request — invalid input (e.g., stopwords-only query, page_size > 100).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Invalid input data." } } } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/search/posts/": { "post": { "summary": "Search posts by content", "description": "Full-text search across post content (captions, descriptions, transcripts) powered by Elasticsearch.\nSupports boolean keyword logic (AND/OR/NOT), exact phrase matching, platform filtering,\nlist filtering, and sorting by relevance or date.\n\nResults are automatically scoped to the organization associated with the API key.\n", "operationId": "public_search_posts_es", "tags": [ "Search" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "q" ], "properties": { "q": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Free-text search query matched against post content. Maximum 500 characters.\n", "example": "brand partnership" }, "exact": { "type": "boolean", "default": false, "description": "When true the query is treated as an exact phrase — the words must appear\nconsecutively and in the given order. When false (default) the query is\ntokenised and matched with partial/fuzzy logic.\n", "example": false }, "must_include_all": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 10, "description": "AND logic — every keyword in this list must be present in the post content. Maximum 10 items, each up to 200 characters.", "example": [ "sponsored", "ad" ] }, "must_not_include": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 10, "description": "NOT logic — none of the keywords in this list should appear in the post content. Maximum 10 items, each up to 200 characters.", "example": [ "giveaway" ] }, "may_include_any": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 10, "description": "OR logic — at least one keyword from this list must be present in the post content. Maximum 10 items, each up to 200 characters.", "example": [ "collab", "partnership" ] }, "sort_by": { "type": "string", "enum": [ "relevance", "posted_at", "-posted_at" ], "default": "relevance", "description": "Sort order for results. `relevance` (default) ranks by search score.\n`posted_at` sorts chronologically (oldest first), `-posted_at` sorts\nreverse-chronologically (newest first).\n", "example": "-posted_at" }, "page": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1, "description": "1-based page number (1–100). Defaults to 1.", "example": 1 }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Number of results per page (1–100). Defaults to 10.", "example": 10 }, "filters": { "type": "object", "description": "Optional nested object with platform, creator, and list filters.", "properties": { "platforms": { "type": "array", "items": { "type": "string", "enum": [ "instagram", "facebook", "youtube", "tiktok", "twitter", "google_news", "reddit" ] }, "description": "Filter results to specific platforms.", "example": [ "instagram", "youtube" ] }, "influencer_id": { "type": "integer", "description": "Filter results to posts belonging to a single creator by their numeric ID.", "example": 12345 }, "list_id": { "type": "string", "format": "uuid", "description": "Filter results to posts from creators in a specific creator list (UUID).", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } } } }, "responses": { "200": { "description": "Successfully retrieved search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSearchResponse" } } } }, "400": { "description": "Bad Request — invalid input (e.g., stopwords-only query, page_size > 100).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Invalid input data." } } } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of the problem.", "example": "Unauthorized" }, "title": { "type": "string", "description": "Short title of the problem.", "example": "Invalid API Key" }, "detail": { "type": "string", "description": "Detailed explanation of the problem.", "example": "The provided API key is invalid." }, "status": { "type": "integer", "description": "HTTP status code.", "example": 401 } } }, "CreatorWithBrands": { "type": "object", "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "Influencer 1" }, "photo_url": { "type": [ "string", "null" ], "example": "https://media.vwd.ai/media/creators-profile-pics/influencer.jpg" }, "region": { "type": [ "string", "null" ], "example": "europe" }, "gender": { "type": [ "string", "null" ], "example": "female" }, "is_public": { "type": "boolean", "example": true }, "followers_reach": { "type": [ "integer", "null" ], "example": 500000 }, "follower_reach_normalised": { "type": "string", "example": "500 k" }, "pronoun": { "type": [ "string", "null" ], "example": "she/her" }, "age": { "type": [ "integer", "null" ], "example": 28 }, "social_profiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "profile_url": { "type": "string", "example": "https://instagram.com/influencer1" }, "platform": { "type": "string", "example": "instagram" }, "social_handle": { "type": "string", "example": "influencer1" } } } }, "scores": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "number", "example": 85.5 } } } }, "summary": { "type": [ "string", "null" ], "example": "Popular lifestyle influencer based in North America" }, "avg_comments_per_post": { "type": "string", "example": "150" }, "avg_likes_per_post": { "type": "string", "example": "5.2 k" }, "avg_views_per_video": { "type": "string", "example": "12.5 k" }, "total_compliance_violations": { "type": "integer", "example": 0 }, "is_monitored": { "type": "boolean", "description": "Indicates whether the creator is currently being monitored (actively scanned for new content).", "example": true }, "brands": { "type": "array", "description": "List of associated brands", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "nike" } } } } } }, "SingleCreatorRequest": { "type": "object", "properties": { "name": { "type": "string", "example": "Jane Doe" }, "social_profiles": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube", "twitter", "facebook" ], "description": "Social media platform name", "example": "instagram" }, "profile_url": { "type": "string", "example": "https://instagram.com/janedoe" } } }, "minItems": 1 }, "confirm_duplicate": { "type": "boolean", "default": false, "description": "When set to true, allows adding creators despite them already existing in the organization.\nDuplicates within the same request are always omitted regardless of this flag.\n", "example": false } }, "required": [ "name", "social_profiles" ] }, "BulkCreatorRequest": { "type": "object", "properties": { "confirm_duplicates": { "type": "boolean", "default": false, "description": "When set to true, allows adding creators despite them already existing in the organization.\nDuplicates within the same request are always omitted regardless of this flag.\n", "example": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "social_profiles": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube", "twitter", "facebook" ], "description": "Social media platform name" }, "profile_url": { "type": "string" } } } } } }, "minItems": 1 } }, "required": [ "items" ] }, "CreatorCreatedResponse": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "name": { "type": "string", "example": "Jane Doe" }, "overall_status": { "type": "string", "example": "pending" }, "is_monitored": { "type": "boolean", "example": false }, "created_at": { "type": "string", "format": "date-time", "example": "2025-01-01T10:00:00Z" }, "social_profiles": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube", "twitter", "facebook" ], "description": "Social media platform name", "example": "instagram" }, "profile_url": { "type": "string", "example": "https://instagram.com/janedoe" } } } } } }, "BulkCreatorResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "example": 0 }, "status": { "type": "string", "enum": [ "created", "invalid", "duplicate_requires_confirmation", "quota_exceeded" ], "example": "created" }, "id": { "type": [ "integer", "null" ], "example": 101 } } } }, "summary": { "type": "object", "properties": { "requested": { "type": "integer", "example": 2 }, "valid": { "type": "integer", "example": 2 }, "created": { "type": "integer", "example": 1 }, "failed": { "type": "integer", "example": 1 } } }, "quota": { "type": "object", "properties": { "limit": { "type": "integer", "example": 1000 }, "used": { "type": "integer", "example": 500 }, "remaining": { "type": "integer", "example": 499 }, "allowed_count": { "type": "integer", "example": 1 }, "reason_code": { "type": "string", "example": "PARTIAL_ALLOWED" } } } } }, "QuotaExceeded": { "type": "object", "properties": { "detail": { "type": "string", "example": "Quota exceeded" }, "limit": { "type": "integer", "example": 1000 }, "used": { "type": "integer", "example": 1000 }, "remaining": { "type": "integer", "example": 0 }, "reason_code": { "type": "string", "example": "LIMIT_REACHED" } } }, "DuplicateDetected": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "warning": { "type": "string", "example": "duplicate_detected" }, "requires_confirmation": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Possible duplicate detected. Set confirm_duplicate to true to proceed." } } }, "CreatorSearchResponse": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of creators matching the query.", "example": 42 }, "total_pages": { "type": "integer", "description": "Total number of pages available at the current page_size.", "example": 5 }, "page": { "type": "integer", "description": "Current page number (1-based).", "example": 1 }, "page_size": { "type": "integer", "description": "Number of results returned per page.", "example": 10 }, "results": { "type": "array", "description": "List of creator search results for the current page.", "items": { "type": "object", "properties": { "influencer_id": { "type": "integer", "description": "Unique numeric identifier for the creator.", "example": 456 }, "name": { "type": "string", "description": "Display name of the creator.", "example": "Jane Fashion" }, "summary": { "type": "string", "description": "Short biography or description of the creator.", "example": "Sustainable fashion creator based in London." }, "region": { "type": [ "string", "null" ], "description": "Geographic region or country associated with the creator.", "example": "europe" }, "followers_reach": { "type": [ "integer", "null" ], "description": "Total follower count aggregated across all connected platforms.", "example": 150000 }, "profile_pic": { "type": "string", "description": "URL of the creator's profile picture.", "example": "https://media.vwd.ai/media/creators-profile-pics/jane.jpg" }, "display_categories": { "type": "object", "additionalProperties": { "type": "object" }, "description": "Content categories detected for this creator, keyed by category slug.", "example": {} }, "compliances": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Compliance violation counts keyed by violation type (e.g., {'ad_disclosure': 3}).", "example": {} }, "platforms": { "type": "array", "description": "List of social platforms the creator is active on.", "items": { "type": "object", "properties": { "platform": { "type": "string", "description": "Platform identifier.", "example": "instagram" }, "profile_id": { "type": "string", "description": "Platform-specific profile identifier.", "example": "janefashion" }, "profile_url": { "type": "string", "description": "Direct URL to the creator's profile on this platform.", "example": "https://instagram.com/janefashion" } } } }, "avg_likes_per_post": { "type": [ "number", "null" ], "description": "Average number of likes per post across all platforms.", "example": 2500 }, "avg_views_per_video": { "type": [ "number", "null" ], "description": "Average number of views per video across all platforms.", "example": 15000 }, "avg_comments_per_post": { "type": [ "number", "null" ], "description": "Average number of comments per post across all platforms.", "example": 120 }, "total_compliance_violations": { "type": [ "integer", "null" ], "description": "Total number of compliance violations detected across all posts.", "example": 2 }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the creator record was created (ISO 8601).", "example": "2024-06-15T10:30:00Z" }, "posts_count": { "type": [ "integer", "null" ], "description": "Number of posts matching the current search query for this creator.", "example": 18 }, "is_monitored": { "type": "boolean", "description": "Indicates whether the creator is currently being monitored (actively scanned for new content).", "example": true } } } } } }, "PostSearchResponse": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of posts matching the query.", "example": 128 }, "total_pages": { "type": "integer", "description": "Total number of pages available at the current page_size.", "example": 13 }, "page": { "type": "integer", "description": "Current page number (1-based).", "example": 1 }, "page_size": { "type": "integer", "description": "Number of results returned per page.", "example": 10 }, "results": { "type": "array", "description": "List of post search results for the current page.", "items": { "type": "object", "properties": { "post_id": { "type": [ "string", "null" ], "description": "Platform-specific post identifier.", "example": "3197321792561269271" }, "influencer_id": { "type": "string", "description": "Numeric identifier of the creator who authored this post.", "example": "456" }, "platform": { "type": "string", "description": "Platform the post originated from.", "example": "instagram" }, "post_url": { "type": "string", "description": "Direct URL to view the post on its native platform.", "example": "https://instagram.com/p/ABC123/" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the post was published (ISO 8601).", "example": "2024-08-20T14:30:00Z" }, "likes_count": { "type": [ "integer", "null" ], "description": "Number of likes (or equivalent reactions) on the post.", "example": 1500 }, "comments_count": { "type": [ "integer", "null" ], "description": "Number of comments on the post.", "example": 42 }, "video_view_count": { "type": [ "integer", "null" ], "description": "Number of video views (null for non-video posts).", "example": null }, "combined_text": { "type": "string", "description": "Full text content of the post (caption, description, transcript, etc.).", "example": "Loving this sustainable fashion brand! #ecofriendly #sustainable" }, "image_url": { "type": [ "string", "null" ], "description": "URL of the post's thumbnail or primary image.", "example": "https://media.vwd.ai/media/post-images/abc123.jpg" }, "influencer_name": { "type": "string", "description": "Display name of the creator who authored this post.", "example": "Jane Fashion" }, "influencer_avatar": { "type": "string", "description": "URL of the creator's profile picture.", "example": "https://media.vwd.ai/media/creators-profile-pics/jane.jpg" }, "title": { "type": [ "string", "null" ], "description": "Article headline (Google News posts only).", "example": null }, "source_name": { "type": [ "string", "null" ], "description": "Name of the news source (Google News posts only).", "example": null }, "display_categories": { "type": "array", "items": { "type": "object" }, "description": "Content categories detected for this post.", "example": [] } } } } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "API key authentication. You must include the 'Api-Key ' prefix before your API key in all requests. Format: `Authorization: Api-Key YOUR_API_KEY_HERE`" } } } }