> ## Documentation Index
> Fetch the complete documentation index at: https://clair.im/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles taxonomy

> Retrieve the closed reviewed role family IDs, names, and sectors accepted by Jobs API filters.



## OpenAPI

````yaml jobs-api/openapi.json GET /v1/taxonomy/roles
openapi: 3.0.3
info:
  title: Clair Job Search API
  version: 1.0.0
  description: >-
    Search normalized active jobs and analyze hiring demand by role, skill,
    company, country, workplace type, and observed salary. Includes source
    provenance, freshness, and canonical taxonomies. Coverage:
    https://clair.im/resources/datasets/active-jobs
servers:
  - url: https://clair-job-search-api.p.rapidapi.com
    description: >-
      RapidAPI gateway. Use the exact host shown on the Clair Job Search API
      listing.
security:
  - rapidApiKey: []
paths:
  /v1/taxonomy/roles:
    get:
      summary: List canonical roles
      description: >-
        Returns the versioned role family IDs, names, and sectors accepted by
        role-aware intelligence endpoints. Closed reviewed vocabulary — not the
        full O*NET occupation list.
      operationId: getRolesTaxonomy
      responses:
        '200':
          description: The complete public role taxonomy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RolesTaxonomyResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    RolesTaxonomyResponse:
      type: object
      required:
        - version
        - count
        - items
      properties:
        version:
          type: string
        count:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/PublicRole'
    PublicRole:
      type: object
      required:
        - id
        - name
        - sector
      properties:
        id:
          type: string
        name:
          type: string
        sector:
          type: string
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Stable machine-readable code. Branch on this value.
          example: bad_cursor
        detail:
          description: >-
            Human-readable detail. Validation errors return an array; typed
            failures return a string. Do not parse this field.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
  responses:
    Unauthorized:
      description: Missing or invalid RapidAPI authorization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: RapidAPI plan rate limit exceeded.
  securitySchemes:
    rapidApiKey:
      type: apiKey
      in: header
      name: X-RapidAPI-Key
      description: >-
        Your RapidAPI subscription key. Also send the `X-RapidAPI-Host` shown on
        the listing.

````