openapi: 3.0.3
info:
  description: API for accessing Contra program and expert data. All endpoints require authentication using an API key.
  title: Contra Public Public Api API
  version: 1.0.0
tags:
- name: Public Api
paths:
  /public-api/programs/{programNid}/filters:
    get:
      parameters:
      - schema:
          type: string
        in: path
        name: programNid
        required: true
      responses:
        '200':
          description: A list of filter definitions for the specified program
          content:
            application/json:
              examples:
                availableFilter:
                  summary: Availability of the expert
                  value:
                    data:
                    - description: Whether the expert is available at this time
                      name: available
                      options:
                      - 'true'
                      - 'false'
                      type: boolean
                languagesFilter:
                  summary: Available languages
                  value:
                    data:
                    - description: Filter experts by spoken languages
                      name: languages
                      options:
                      - English
                      - American Sign Language
                      type: string
                locationsFilter:
                  summary: Available locations
                  value:
                    data:
                    - description: Filter experts by geographic location (with place ID)
                      name: locations
                      options:
                      - San Francisco CA, USA (ChIJIQBpAG2ahYAR_6128GcTUEo)
                      - New York NY, USA (ChIJIQBpAG2ahYAR_6128GcTUEo)
                      - Los Angeles CA, USA (ChIJIQBpAG2ahYAR_6128GcTUEo)
                      - Chicago IL, USA (ChIJIQBpAG2ahYAR_6128GcTUEo)
                      - Austin TX, USA (ChIJIQBpAG2ahYAR_6128GcTUEo)
                      - Seattle WA, USA (ChIJIQBpAG2ahYAR_6128GcTUEo)
                      type: string
                maxRateFilter:
                  summary: Maximum hourly rate filter
                  value:
                    data:
                    - description: Filter experts by maximum hourly rate (USD)
                      maximum: 1000
                      minimum: 0
                      name: maxRate
                      type: number
                minRateFilter:
                  summary: Minimum hourly rate filter
                  value:
                    data:
                    - description: Filter experts by minimum hourly rate (USD)
                      maximum: 1000
                      minimum: 0
                      name: minRate
                      type: number
                sortByFilter:
                  summary: Sort order options
                  value:
                    data:
                    - description: Sort order for results
                      name: sortBy
                      options:
                      - relevance
                      - oldest
                      - newest
                      type: string
              schema:
                $ref: '#/components/schemas/FilterListResponse'
      tags:
      - Public Api
  /public-api/programs/{programNid}:
    get:
      parameters:
      - schema:
          type: string
        in: path
        name: programNid
        required: true
      responses:
        '200':
          description: Program details
          content:
            application/json:
              examples:
                programSummaryExample:
                  summary: Framer program summary
                  value:
                    data:
                      applyUrl: https://www.framer.com/dashboard/templates/?profile=expert
                      expertsCount: 42
                      hireUrl: https://contra.com/framer?showCreateJobModal=true
                      id: abc_123
                      logoUrl: https://media.contra.com/image/upload/r_max,w_200,h_200/framer.png
                      subheader: Build your next project with a Framer expert
                      title: Framer Experts
                      totalHires: 100
                      totalHireValue: 123456.78
                      totalReviews: 250
              schema:
                $ref: '#/components/schemas/ProgramSummaryResponse'
      tags:
      - Public Api
  /public-api/programs/{programNid}/experts:
    get:
      parameters:
      - schema:
          type: string
          enum:
          - 'true'
          - 'false'
        examples:
          'true':
            value: 'true'
          'false':
            value: 'false'
        in: query
        name: available
        description: Filter by availability status
      - schema:
          anyOf:
          - type: string
          - type: array
            items:
              type: string
        examples:
          English:
            value: English
          English,French:
            value: English,French
          Mandarin:
            value: Mandarin
        in: query
        name: languages
        description: 'Filter by languages. Can be a single language or multiple languages separated by commas: ?languages=English,French'
      - schema:
          type: string
        examples:
          '10':
            value: '10'
          '20':
            value: '20'
          '50':
            value: '50'
        in: query
        name: limit
        description: Number of results to return per page
      - schema:
          type: string
        examples:
          San Francisco CA, USA (ChIJIQBpAG2ahYAR_6128GcTUEo):
            value: San Francisco CA, USA (ChIJIQBpAG2ahYAR_6128GcTUEo)
          New York NY, USA (ChIJIQBpAG2ahYAR_6128GcTUEo):
            value: New York NY, USA (ChIJIQBpAG2ahYAR_6128GcTUEo)
        in: query
        name: location
        description: Filter by location (with Google Place ID)
      - schema:
          type: string
        examples:
          '100':
            value: '100'
          '150':
            value: '150'
          '200':
            value: '200'
        in: query
        name: maxRate
        description: Maximum hourly rate in USD
      - schema:
          type: string
        examples:
          '50':
            value: '50'
          '75':
            value: '75'
          '100':
            value: '100'
        in: query
        name: minRate
        description: Minimum hourly rate in USD
      - schema:
          type: string
        examples:
          '0':
            value: '0'
          '10':
            value: '10'
          '20':
            value: '20'
        in: query
        name: offset
        description: Number of results to skip (for pagination)
      - schema:
          type: string
          enum:
          - relevance
          - oldest
          - newest
        examples:
          relevance:
            value: relevance
          oldest:
            value: oldest
          newest:
            value: newest
        in: query
        name: sortBy
        description: Sort order for results
      - schema:
          type: string
        in: path
        name: programNid
        required: true
      responses:
        '200':
          description: List of expert profiles
          content:
            application/json:
              examples:
                pagedExpertsExample:
                  summary: First page of experts
                  value:
                    data:
                    - available: true
                      avatarUrl: https://media.contra.com/image/upload/r_max,w_200,h_200/jane-doe.jpg
                      earningsUSD: 75000.5
                      followersCount: 200
                      hourlyRateUSD: 120
                      id: exp_12345
                      inquiryUrl: https://contra.com/inquiry/janedoe
                      location: San Francisco CA, USA (ChIJIQBpAG2ahYAR_6128GcTUEo)
                      name: Jane Doe
                      oneLiner: Full-stack developer specializing in React and Node.js
                      profileUrl: https://contra.com/janedoe
                      projects:
                      - coverUrl: https://media.contra.com/image/upload/r_max,w_200,h_200/ecommerce-cover.jpg
                        projectUrl: https://contra.com/p/YLZWOR7m-ecommerce-platform
                        title: E-commerce Platform
                      - coverUrl: https://media.contra.com/image/upload/r_max,w_200,h_200/marketing-cover.jpg
                        projectUrl: https://contra.com/p/eMOoOeFO/marketing-website
                        title: Marketing Website
                      projectsCompletedCount: 15
                      reviews:
                      - author:
                          authorFullName: John Doe
                          authorProfileUrl: https://contra.com/janedoe
                          companyName: Acme Inc
                          companyProfileUrl: https://contra.com/acme
                        createdAt: '2021-01-01'
                        id: 123
                        rating: 5
                        review: This is a positive review
                        reviewUrl: https://contra.com/janedoe/reviews/?highlightedReviewId=abc123
                      reviewsCount: 30
                      skillTags:
                      - React
                      - Node.js
                      - TypeScript
                      socialLinks:
                      - label: twitter
                        url: https://twitter.com/janedoe
                      - label: linkedin
                        url: https://linkedin.com/in/janedoe
                    totalCount: 200
              schema:
                $ref: '#/components/schemas/ExpertProfileList'
      tags:
      - Public Api
components:
  schemas:
    ProgramSummary:
      type: object
      nullable: true
      properties:
        applyUrl:
          type: string
          format: uri
          description: URL for experts to apply
        expertsCount:
          type: integer
          description: Number of experts in the program
        hireUrl:
          type: string
          format: uri
          description: URL where clients can hire experts
        id:
          type: string
          description: Expert program identifier
        logoUrl:
          type: string
          format: uri
          description: URL to program logo image
        subheader:
          type: string
          description: Short description or tagline
        title:
          type: string
          description: Program title
        totalHires:
          type: integer
          description: Total number of hires
        totalHireValue:
          type: number
          description: Cumulative value of all hires (USD)
        totalReviews:
          type: integer
          description: Total reviews received by program experts
      required:
      - applyUrl
      - expertsCount
      - hireUrl
      - id
      - logoUrl
      - subheader
      - title
      - totalHires
      - totalHireValue
      - totalReviews
    ExpertProfile:
      type: object
      properties:
        available:
          type: boolean
          description: Availability status
        avatarUrl:
          type: string
          format: uri
          description: URL to avatar image
        averageReviewScore:
          type: number
          description: Average review score
        earningsUSD:
          type: number
          description: Total earnings on Contra (USD)
        emailAddress:
          type: string
          nullable: true
          format: email
          description: Normalized email address (if permitted)
        followersCount:
          type: integer
          description: Followers count
        hourlyRateUSD:
          type: number
          nullable: true
          description: Rate per hour in USD
        id:
          type: string
          description: Expert identifier
        inquiryUrl:
          type: string
          format: uri
          description: Inquiry modal URL
        location:
          type: string
          description: Country or region
        name:
          type: string
          description: Full name
        oneLiner:
          type: string
          description: Short bio tagline
        profileUrl:
          type: string
          format: uri
          description: Contra profile URL
        projects:
          type: array
          items:
            type: object
            properties:
              coverUrl:
                type: string
                format: uri
                description: Cover image URL
              projectUrl:
                type: string
                format: uri
                description: Project page URL
              title:
                type: string
                description: Project title
            required:
            - coverUrl
            - projectUrl
            - title
          description: Project samples
        projectsCompletedCount:
          type: integer
          description: Completed projects count
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/Review'
          description: Reviews
        reviewsCount:
          type: integer
          description: Total reviews
        skillTags:
          type: array
          items:
            type: string
          description: Skills or technologies
        socialLinks:
          type: array
          items:
            type: object
            properties:
              label:
                type: string
                nullable: true
                description: Social platform
              url:
                type: string
                format: uri
                description: Social URL
            required:
            - label
            - url
          description: Map of social platform to URL
      required:
      - available
      - avatarUrl
      - averageReviewScore
      - earningsUSD
      - emailAddress
      - followersCount
      - hourlyRateUSD
      - id
      - inquiryUrl
      - location
      - name
      - oneLiner
      - profileUrl
      - projects
      - projectsCompletedCount
      - reviews
      - reviewsCount
      - skillTags
      - socialLinks
    Review:
      type: object
      properties:
        author:
          type: object
          properties:
            authorFullName:
              type: string
              description: Author name
            authorProfileUrl:
              type: string
              format: uri
              description: Author profile URL
            companyName:
              type: string
              nullable: true
              description: Author company name
            companyProfileUrl:
              type: string
              nullable: true
              format: uri
              description: Author company profile URL
          required:
          - authorFullName
          - authorProfileUrl
          - companyName
          - companyProfileUrl
        createdAt:
          type: string
          description: Review creation date
        rating:
          type: number
          description: Review rating
        review:
          type: string
          nullable: true
          description: Review text
        reviewUrl:
          type: string
          format: uri
          description: Review URL
      required:
      - author
      - createdAt
      - rating
      - review
      - reviewUrl
    FilterListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Filter'
      required:
      - data
    ExpertProfileList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ExpertProfile'
          description: Array of expert profiles
        totalCount:
          type: integer
          description: Total number of expert profiles
      required:
      - data
      - totalCount
    ProgramSummaryResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ProgramSummary'
      required:
      - data
    Filter:
      type: object
      properties:
        description:
          type: string
          description: Human-readable description of the filter
        maximum:
          type: number
          description: Maximum allowable value (for range filters)
        minimum:
          type: number
          description: Minimum allowable value (for range filters)
        name:
          type: string
          description: Field name to filter by
        options:
          type: array
          items:
            type: string
          description: Allowed values (for enum filters)
        type:
          type: string
          enum:
          - string
          - number
          - boolean
          description: Data type of the filter
      required:
      - description
      - name
      - type
      examples:
      - description: Filter experts by location
        name: location
        options:
        - San Francisco CA, USA (ChIJIQBpAG2ahYAR_6128GcTUEo)
        - New York NY, USA (ChIJIQBpAG2ahYAR_6128GcTUEo)
        type: string
      - description: Filter experts by spoken languages
        name: languages
        options:
        - English
        - Spanish
        - French
        type: string
      - description: Filter experts by availability
        name: available
        options:
        - 'true'
        - 'false'
        type: boolean
      - description: Sort order options
        name: sortBy
        options:
        - relevance
        - oldest
        - newest
        type: string
      - description: Minimum hourly rate in USD
        maximum: 1000
        minimum: 0
        name: minRate
        type: number
      - description: Maximum hourly rate in USD
        maximum: 1000
        minimum: 0
        name: maxRate
        type: number
      - description: Number of results per page
        maximum: 100
        minimum: 1
        name: limit
        type: number
      - description: Number of results to skip
        minimum: 0
        name: offset
        type: number