openapi: 3.0.3
info:
  title: Snapchat Public Profile API
  description: |
    The Snapchat Public Profile API provides access to public metadata and statistics about Public Profiles and their content. The API enables two primary functions: Creator Discovery and Content Management.
    
    **Key Features:**
    - **Creator Discovery**: Find the right creators for brand partnerships with public metrics and audience insights
    - **Content Management**: Post content on behalf of brands or creators, view analytics, and promote with paid media
    - **Public Profiles**: Access brand and creator content within Snapchat, supporting both verified and unverified profiles
    - **Content Types**: Stories, Saved Stories, Spotlights, and Lenses
    
    **Profile Categories & Tiers:**
    - PUBLIC Person: Emerging creators eligible for monetization
    - PUBLIC OFFICIAL Person: Verified Snap Stars
    - PUBLIC Business: Business profiles with advanced features  
    - PUBLIC OFFICIAL Business: Official verified businesses
    
    **Endpoint Types:**
    - **Public Endpoints** (`/public/v1/`): No profile owner authorization required, basic metadata only
    - **Authorized Endpoints** (`/v1/`): Require profile owner authorization or data sharing opt-in
    
    **Base URL:** https://businessapi.snapchat.com
    **Authentication:** OAuth 2.0 with Bearer tokens
    **Scope:** snapchat-profile-api
  version: '1.0'
  contact:
    name: Snapchat for Developers
    url: https://developers.snap.com/api/marketing-api/Public-Profile-API/Introduction
  license:
    name: Snapchat Terms of Service
    url: https://snap.com/en-US/terms/

servers:
  - url: https://businessapi.snapchat.com
    description: Production server

security:
  - OAuth2: [snapchat-profile-api]

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.snapchat.com/login/oauth2/authorize
          tokenUrl: https://accounts.snapchat.com/login/oauth2/access_token
          refreshUrl: https://accounts.snapchat.com/login/oauth2/access_token
          scopes:
            snapchat-profile-api: Access to Public Profile API endpoints

  schemas:
    PublicProfile:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: UUID of the profile
        organization_id:
          type: string
          format: uuid
          description: UUID of the organization the profile belongs to
        display_name:
          type: string
          description: Profile display name
        description:
          type: string
          description: Optional description of the profile
        category:
          type: string
          enum: [CATEGORY_V3_UNKNOWN, CATEGORY_V3_BUSINESS_GROUP, CATEGORY_V3_PEOPLE, CATEGORY_V3_PRODUCT_BRAND]
          description: Category of the profile
        subcategory:
          type: string
          description: Sub category of the profile
        email:
          type: string
          description: Optional email for the profile
        phone_number:
          type: string
          description: Optional phone number for the profile
        website:
          type: string
          description: Optional website URL for the profile
        logo_urls:
          $ref: '#/components/schemas/LogoUrls'
        address_line_1:
          type: string
          description: Optional address for the profile
        address_line_2:
          type: string
          description: Optional address for the profile
        address_line_3:
          type: string
          description: Optional address for the profile
        locality:
          type: string
          description: Optional locality (city) for the profile
        administrative_district_level_1:
          type: string
          description: Optional state for the profile
        administrative_district_level_2:
          type: string
          description: Optional state for the profile
        postal_code:
          type: string
          description: Optional zipcode for the profile
        l_90_country_code:
          type: string
          description: Two-letter country code of profile owner's location over past 90 days
        country:
          type: string
          description: Country code of the profile
        snap_user_name:
          type: string
          description: Snap username this profile is hosted on
        store_id:
          type: string
          format: uuid
          description: Optional store ID if profile is linked to a store
        profile_type:
          type: string
          enum: [STORY_STUDIO_PUBLISHER, PUBLISHER_WITH_HOST_USER, PUBLIC_PROFILE, PUBLIC_PROFILE_WITH_PUBLISHER_CONTENT]
          description: Profile type
        profile_tier:
          type: string
          enum: [TIER_UNKNOWN, TIER_STANDARD, TIER_PUBLIC, TIER_PUBLIC_OFFICIAL]
          description: Profile tier
        profile_icon_primary_color_hex:
          type: string
          description: Hex color value representing most prominent color in Profile Icon
        internal_profile_category:
          type: string
          enum: [UNKNOWN, BUSINESS, PERSON, PUBLISHER]
          description: Internal profile category
        subscriber_count:
          type: string
          description: Number of subscribers that the profile has
        spotlight_views:
          type: string
          description: Number of spotlight views (last 24 hours)
        share_authorized_data_with_api_partners:
          type: boolean
          description: Indicates if authorized profile data is shared with API partners

    LogoUrls:
      type: object
      properties:
        original_logo_url:
          type: string
          description: URL string for original logo image, 1280px wide
        discover_feed_logo_url:
          type: string
          description: URL string for logo image, 72px wide
        mega_profile_logo_url:
          type: string
          description: URL string for logo image, 90px wide
        manage_profile_logo_url:
          type: string
          description: URL string for logo image, 640px wide

    PublicProfileResponse:
      type: object
      properties:
        sub_request_status:
          type: string
          enum: [SUCCESS, ERROR, PARTIAL]
          description: Status of the sub-request
        public_profile:
          $ref: '#/components/schemas/PublicProfile'
        sub_request_error_reason:
          type: string
          description: Error reason if sub_request_status is ERROR or PARTIAL

    ApiResponse:
      type: object
      properties:
        request_id:
          type: string
          format: uuid
          description: UUID of the request
        request_status:
          type: string
          enum: [SUCCESS, ERROR, PARTIAL]
          description: Status of the request
        debug_message:
          type: string
          description: Debug information if request_status is ERROR or PARTIAL
        display_message:
          type: string
          description: Display information if request_status is ERROR or PARTIAL
        error_code:
          type: string
          description: Error code if request_status is ERROR or PARTIAL

    ProfileListResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            public_profiles:
              type: array
              items:
                $ref: '#/components/schemas/PublicProfileResponse'
            paging:
              $ref: '#/components/schemas/Paging'

    SingleProfileResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            public_profiles:
              type: array
              items:
                $ref: '#/components/schemas/PublicProfileResponse'
              maxItems: 1

    MyProfileResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            public_profile:
              $ref: '#/components/schemas/PublicProfile'

    Paging:
      type: object
      properties:
        next_page_id:
          type: string
          description: Encoded string for next page cursor
        next_link:
          type: string
          description: Encoded URL string with original base URL, limit, and cursor

    ChangeLog:
      type: object
      properties:
        url:
          type: string
          description: Signed URL to the change log file

    ChangeLogResponse:
      type: object
      properties:
        sub_request_status:
          type: string
          enum: [SUCCESS, ERROR, PARTIAL]
        change_log:
          $ref: '#/components/schemas/ChangeLog'

    ChangeLogsResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            change_logs:
              type: array
              items:
                $ref: '#/components/schemas/ChangeLogResponse'

    ProfileIdResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            profile_id:
              type: string
              format: uuid
              description: UUID of the creator's profile

    SharedSnap:
      type: object
      properties:
        id:
          type: string
          description: Snap ID
        story_id:
          type: string
          format: uuid
          description: ID of the full story
        media_metadata:
          $ref: '#/components/schemas/MediaMetadata'
        created_at:
          type: string
          format: date-time
          description: When the snap was created
        sponsor:
          $ref: '#/components/schemas/Sponsor'
        username:
          type: string
          description: Snap username of the creator tagging the brand
        display_name:
          type: string
          description: Display name of the creator's public profile
        multi_snaps_bundle_id:
          type: string
          description: Bundle ID for when story > 10s
        story_type:
          type: string
          description: Type of story (e.g., SAVED_STORY)

    MediaMetadata:
      type: object
      properties:
        media_type:
          type: string
          enum: [MEDIA_TYPE_IMAGE, MEDIA_TYPE_VIDEO]
          description: Type of media
        media_url:
          type: string
          description: URL to the media content
        thumbnail_url:
          type: string
          description: URL to the thumbnail

    Sponsor:
      type: object
      properties:
        profile_id:
          type: string
          format: uuid
          description: Profile ID of the brand being tagged
        display_name:
          type: string
          description: Display name of the brand
        sponsor_status:
          type: string
          enum: [PENDING, REJECTED, NOT_SPECIFIED, AUTO_APPROVED]
          description: Status of the sponsorship

    SharedSnapResponse:
      type: object
      properties:
        sub_request_status:
          type: string
          enum: [SUCCESS, ERROR, PARTIAL]
        shared_snap:
          $ref: '#/components/schemas/SharedSnap'

    SharedSnapsResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            shared_snaps:
              type: array
              items:
                $ref: '#/components/schemas/SharedSnapResponse'

    ClaimMediaResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            media_entity_id:
              type: string
              format: uuid
              description: ID of the claimed media entity

paths:
  # Public Endpoints - No authorization required
  /public/v1/public_profiles/change_logs:
    get:
      summary: List Public Profile Change Logs
      description: Returns a list of signed URLs to change logs containing IDs of public profiles that were created, modified, or deleted.
      operationId: listChangeLogss
      parameters:
        - name: start_at_timestamp
          in: query
          description: Timestamp to filter profiles created or updated after this date
          required: false
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          description: Number of change logs to return per page (default 100)
          required: false
          schema:
            type: integer
            minimum: 1
            default: 100
        - name: cursor
          in: query
          description: Encoded cursor for next page
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeLogsResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '500':
          description: Internal server error

  /public/v1/public_profiles/discover:
    get:
      summary: Discover Creators
      description: Search for creators based on follower count, spotlight views, country, and other filters. Results are sorted by follower count.
      operationId: discoverCreators
      parameters:
        - name: limit
          in: query
          description: Number of results to return per page (default 100)
          required: false
          schema:
            type: integer
            minimum: 1
            default: 100
        - name: cursor
          in: query
          description: Pagination encoded cursor for next page
          required: false
          schema:
            type: string
        - name: creator_l_90_country_codes
          in: query
          description: Creator's country code(s) (ISO 3166-1 alpha-2)
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
              pattern: '^[A-Z]{2}$'
        - name: creator_categories
          in: query
          description: Creator's subcategories
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: min_followers
          in: query
          description: Minimum number of followers
          required: false
          schema:
            type: integer
            minimum: 0
        - name: max_followers
          in: query
          description: Maximum number of followers
          required: false
          schema:
            type: integer
            minimum: 0
        - name: min_spotlight_views
          in: query
          description: Minimum spotlight views (last 24 hours)
          required: false
          schema:
            type: integer
            minimum: 0
        - name: max_spotlight_views
          in: query
          description: Maximum spotlight views (last 24 hours)
          required: false
          schema:
            type: integer
            minimum: 0
        - name: can_share_data
          in: query
          description: Only include creators who opt to share authorized data
          required: false
          schema:
            type: boolean
        - name: query
          in: query
          description: Keyword search on username and display name
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileListResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '500':
          description: Internal server error

  /public/v1/public_profiles/search:
    get:
      summary: Search for Profiles
      description: Returns a list of public profiles that match the search criteria by username or display name.
      operationId: searchProfiles
      parameters:
        - name: query
          in: query
          description: Snap username or profile display name to search by
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of profiles to return (default 100)
          required: false
          schema:
            type: integer
            minimum: 1
            default: 100
        - name: category
          in: query
          description: Profile category
          required: false
          schema:
            type: string
            enum: [CATEGORY_PERSON, CATEGORY_BUSINESS]
            default: CATEGORY_BUSINESS
        - name: tier
          in: query
          description: Profile tier
          required: false
          schema:
            type: string
            enum: [TIER_PUBLIC, TIER_PUBLIC_OFFICIAL]
            default: TIER_PUBLIC_OFFICIAL
        - name: includeStandard
          in: query
          description: Whether to include standard tier public profiles
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileListResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '500':
          description: Internal server error

  /public/v1/public_profiles/{profile_id}:
    get:
      summary: Get Profile by ID (Public)
      description: Retrieves public metadata of a Public Profile by its ID. No authorization required.
      operationId: getPublicProfileById
      parameters:
        - name: profile_id
          in: path
          description: Profile ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleProfileResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Profile not found
        '500':
          description: Internal server error

  /public/v1/snaps/{snap_id}/public_profile:
    get:
      summary: Get Profile by Snap ID
      description: Retrieves a user's public profile ID given the snap ID of a snap they created.
      operationId: getProfileBySnapId
      parameters:
        - name: snap_id
          in: path
          description: Snap ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileIdResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Snap not found
        '500':
          description: Internal server error

  # Authorized Endpoints - Require authorization
  /v1/organizations/{organization_id}/public_profiles:
    get:
      summary: Get Profiles by Organization ID
      description: Returns all profiles that the user has permission to access in the designated organization.
      operationId: getProfilesByOrganization
      parameters:
        - name: organization_id
          in: path
          description: Organization ID
          required: true
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          description: Pagination limit size (default 10)
          required: false
          schema:
            type: integer
            minimum: 1
            default: 10
        - name: cursor
          in: query
          description: Pagination encoded cursor for next page
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileListResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Authorization permission denied
        '500':
          description: Internal server error

  /v1/public_profiles/{profile_id}:
    get:
      summary: Get Profile by ID (Authorized)
      description: Retrieves detailed profile information for authorized profiles. Requires profile owner authorization.
      operationId: getAuthorizedProfileById
      parameters:
        - name: profile_id
          in: path
          description: Profile ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleProfileResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Authorization permission denied
        '404':
          description: Profile not found
        '500':
          description: Internal server error

  /v1/public_profiles/my_profile:
    get:
      summary: Get My Profile
      description: Retrieves the current user's public profile given their auth token.
      operationId: getMyProfile
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MyProfileResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '500':
          description: Internal server error

  /v1/public_profiles/{profile_id}/shared_snaps:
    get:
      summary: Retrieve Collaboration Snaps
      description: Retrieves paid partnership posts where the brand is tagged by a creator.
      operationId: getCollaborationSnaps
      parameters:
        - name: profile_id
          in: path
          description: Profile ID of the brand being tagged
          required: true
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          description: Pagination limit size (default 10)
          required: false
          schema:
            type: integer
            minimum: 1
            default: 10
        - name: cursor
          in: query
          description: Pagination encoded cursor for next page
          required: false
          schema:
            type: string
        - name: fetch_in_aggregate_view
          in: query
          description: Include Story ID and Story type in response (default true)
          required: false
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedSnapsResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Authorization permission denied
        '404':
          description: Profile not found
        '500':
          description: Internal server error

  /v1/adaccounts/{adAccountId}/claim_media_by_snap_reference:
    post:
      summary: Claim Media for Advertising
      description: Turns an organic paid partnership post into an ad by claiming the media.
      operationId: claimMediaBySnapReference
      parameters:
        - name: adAccountId
          in: path
          description: Ad account ID
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - snap_id
              properties:
                snap_id:
                  type: string
                  format: uuid
                  description: ID of the organic content to be turned into an ad
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimMediaResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Authorization permission denied
        '500':
          description: Internal server error

tags:
  - name: Public Endpoints
    description: Endpoints that don't require profile owner authorization
  - name: Authorized Endpoints
    description: Endpoints that require profile owner authorization or data sharing opt-in
  - name: Creator Discovery
    description: Find and search for creators and public profiles
  - name: Profile Management
    description: Retrieve and manage public profile information
  - name: Content Collaboration
    description: Manage brand-creator collaboration content