openapi: 3.1.0
info:
  title: Paradox Authentication Company API
  description: API for the Paradox conversational AI recruiting platform powered by Olivia. Provides endpoints for managing candidates, users, interview scheduling, locations, company data, reporting, and candidate attributes. Paradox automates candidate screening, interview scheduling, and hiring workflows through chat, SMS, and mobile-driven experiences.
  version: 1.0.0
  contact:
    name: Paradox Support
    url: https://www.paradox.ai/contact
    email: support@paradox.ai
  license:
    name: Proprietary
    url: https://www.paradox.ai/legal/service-terms
  termsOfService: https://www.paradox.ai/legal/service-terms
servers:
- url: https://api.paradox.ai/api/v1/public
  description: Production (US)
- url: https://api.eu1.paradox.ai/api/v1/public
  description: Production (EU)
- url: https://stgapi.paradox.ai/api/v1/public
  description: Staging (US)
- url: https://api.stg.eu1.paradox.ai/api/v1/public
  description: Staging (EU)
- url: https://testapi.paradox.ai/api/v1/public
  description: Test
- url: https://dev2api.paradox.ai/api/v1/public
  description: Development
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Company
  description: Access company-level data including conversations, groups, schools, areas, and AI assistant
paths:
  /company/conversations:
    get:
      operationId: getCompanyConversations
      summary: Paradox Get company conversations
      description: Retrieve all conversation configurations for the company.
      tags:
      - Company
      responses:
        '200':
          description: Conversations returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  conversations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Conversation'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /company/groups:
    get:
      operationId: getCompanyGroups
      summary: Paradox Get company groups
      description: Retrieve all groups configured for the company.
      tags:
      - Company
      responses:
        '200':
          description: Groups returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  groups:
                    type: array
                    items:
                      $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /company/school_areas:
    get:
      operationId: getCompanySchoolAreas
      summary: Paradox Get company schools and areas
      description: Retrieve all schools and areas configured for the company.
      tags:
      - Company
      responses:
        '200':
          description: Schools and areas returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  school_areas:
                    type: array
                    items:
                      $ref: '#/components/schemas/SchoolArea'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /company/ai:
    get:
      operationId: getCompanyAiAssistant
      summary: Paradox Get AI assistant
      description: Retrieve the AI assistant name and image configuration.
      tags:
      - Company
      responses:
        '200':
          description: AI assistant details returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiAssistant'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    AiAssistant:
      type: object
      description: AI assistant configuration
      properties:
        id:
          type: string
          description: Assistant identifier
        ai_name:
          type: string
          description: AI assistant display name
        ai_logo_uri:
          type: string
          format: uri
          description: AI assistant logo image URL
    Conversation:
      type: object
      description: A conversation configuration
      properties:
        oid:
          type: string
          description: Conversation identifier
        label:
          type: string
          description: Conversation name/label
        is_remote:
          type: integer
          enum:
          - 0
          - 1
          description: Whether the conversation is for remote positions
        deactivated:
          type: integer
          enum:
          - 0
          - 1
          description: Whether the conversation is deactivated
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
    SchoolArea:
      type: object
      description: A school or area associated with the company
      properties:
        oid:
          type: string
          description: School/area identifier
        name:
          type: string
          description: School/area name
        type:
          type: integer
          enum:
          - 1
          - 2
          description: 'Type: 1=area, 2=school'
    Group:
      type: object
      description: A company group
      properties:
        oid:
          type: string
          description: Group identifier
        name:
          type: string
          description: Group name
  responses:
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                const: false
              message:
                type: string
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 client credentials authentication
      flows:
        clientCredentials:
          tokenUrl: /auth/token
          scopes: {}
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token obtained from the OAuth 2.0 token endpoint
externalDocs:
  description: Paradox API Documentation
  url: https://readme.paradox.ai/docs