openapi: 3.1.0
info:
  title: VwD External API
  description: External API for accessing VwD creators data.
  version: 1.0.0
  contact:
    name: VwD API Support
    email: hello@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.
  - name: X-Ray
    description: Endpoints for retrieving creators posts with labels.
  - name: X-Ray Brands
    description: Endpoints for creators posts and timelines related to brands.
  - name: X-Ray Compliance
    description: Endpoints for creators compliance data.
paths:
  /creators/search:
    post:
      summary: Search and list creators
      description: >
        **Public API Endpoint**


        Use this endpoint to search creators based on various filters, with
        support for pagination and ordering. 

        This is a POST request and requires an API key for authentication.


        Provide filters to narrow down the search results. If no filters are
        provided, all creators are listed with pagination applied.
      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
        - name: page
          in: query
          required: false
          schema:
            type: integer
          description: Page number for pagination.
          example: 1
        - 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'
      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_bullying_content:
                      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.qa.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
        '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**


        Use this endpoint to retrieve an creator's profile. Only accessible if
        the API key is valid and the creators 

        belongs to the organization associated with the API key.
      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
      responses:
        '200':
          description: Successfully retrieved the creators profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Creator'
        '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**


        Fetch all posts for a specific creators tagged with the specified media
        category.  

        Optional year and month parameters can be used to filter posts by
        date.  

        Requires an API key for authentication.
      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
        - name: month
          in: query
          description: Month for filtering posts (optional).
          required: false
          schema:
            type: integer
        - name: media_category
          in: query
          description: Category of media for filtering posts (e.g., 'alcoholic_beverages').
          required: true
          schema:
            type: string
            enum:
              - alcoholic_beverages
              - graphic_violence
              - religious_content
              - sexual_content
              - hate_content
              - gambling_content
              - drug_content
              - cyber_bullying
      responses:
        '200':
          description: A list of posts with labels.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    platform_name:
                      type: string
                      description: Platform name.
                      example: Instagram
                    date:
                      type: string
                      format: date
                      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 score of the post.
                      example: 95.5
                    categories:
                      type: array
                      items:
                        type: string
                      description: Categories associated with the post.
                      example:
                        - alcoholic_beverages
        '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}/timeline:
    get:
      summary: Retrieve creators Timeline by Media Category
      description: >
        **Public API Endpoint**


        Fetch a timeline of posts for a given creators based on the specified
        media category.  

        The response groups posts by year and month.  

        Requires an API key for authentication.
      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: Media category to filter posts by (e.g., 'politics_content').
          required: true
          schema:
            type: string
            enum:
              - alcoholic_beverages
              - graphic_violence
              - religious_content
              - sexual_content
              - hate_content
              - gambling_content
              - drug_content
              - cyber_bullying
      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**


        Fetch a timeline of posts for a given creators mentioning a specific
        brand.  

        The timeline groups posts by year and month.  

        Requires an API key for authentication.
      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_id
          in: query
          description: ID of the brand to filter posts by.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Timeline of posts mentioning the brand, 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 ID.
          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**

        Fetch all posts for a specific creators mentioning a given brand.  
        Optional filters for year and month can be applied.  
        Requires an API key for authentication.
      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_id
          in: query
          description: ID of the brand.
          required: true
          schema:
            type: integer
        - name: year
          in: query
          description: Year filter for posts (optional).
          required: false
          schema:
            type: integer
        - name: month
          in: query
          description: Month filter for posts (optional).
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: List of posts mentioning the brand, with details.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    platform_name:
                      type: string
                      description: Platform name where the post was published.
                      example: Instagram
                    date:
                      type: string
                      format: date
                      description: Date of the post.
                      example: January 1, 2024
                    link:
                      type: string
                      description: URL link to the post.
                      example: https://instagram.com/post/12345
        '204':
          description: No posts found for the specified parameters.
        '400':
          description: Missing or invalid parameters (e.g., creators ID or brand ID).
          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**

        Fetch a timeline of compliance violations for a given creators.  
        The response groups compliance violations by year and month.  
        Requires an API key for authentication.
      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: Key for the compliance category to filter violations.
          required: true
          schema:
            type: string
            enum:
              - FTC
              - FINRA
              - Healthcare
      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**

        Fetch all posts for a given creators with compliance violations.  
        Optional filters for year and month can be applied.  
        Requires an API key for authentication.
      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: Key for the compliance category to filter violations.
          required: true
          schema:
            type: string
            enum:
              - FTC
              - FINRA
              - Healthcare
        - name: year
          in: query
          description: Year filter for posts (optional).
          required: false
          schema:
            type: integer
        - name: month
          in: query
          description: Month filter for posts (optional).
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: List of posts with compliance violations.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    platform_name:
                      type: string
                      description: Platform name where the post was published.
                      example: Instagram
                    date:
                      type: string
                      format: date
                      description: Date of the post.
                      example: January 1, 2024
                    link:
                      type: string
                      description: URL link to the post.
                      example: https://instagram.com/post/12345
                    compliance_categories:
                      type: array
                      items:
                        type: string
                      description: List of compliance categories associated with the post.
                      example:
                        - False Advertising
        '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'
components:
  schemas:
    Creator:
      type: object
      properties:
        id:
          type: integer
          example: 3975
        name:
          type: string
          example: BMW
        photo_url:
          type: string
          example: https://media.qa.vwd.ai/media/creators-profile-pics/bmw.jpg
        region:
          type: string
          example: india
        gender:
          type: string
          example: non_binary
        followers_reach:
          type: integer
          example: 40337817
        social_profiles:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                example: 4750
              profile_url:
                type: string
                example: https://www.instagram.com/bmw
              platform:
                type: string
                example: instagram
              social_handle:
                type: string
                example: bmw
        scores:
          type: object
          additionalProperties:
            type: object
            properties:
              value:
                type: number
                example: 1.38
        summary:
          type: string
          example: BMW is a non-binary creators based in India, active on Instagram.
    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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use your API key for authentication. Format: `Api-Key your-api-key`'
