> ## 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.

# Top skills

> Rank skill demand across active postings with optional role, country, workplace, and seniority filters.



## OpenAPI

````yaml jobs-api/openapi.json GET /v1/top-skills
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/top-skills:
    get:
      summary: Rank skills in active postings
      description: >-
        Ranks canonical skills mentioned in active postings. Optionally filter
        by normalized role, country, workplace type, or seniority.
      operationId: getTopSkills
      parameters:
        - $ref: '#/components/parameters/Country'
        - $ref: '#/components/parameters/WorkplaceType'
        - $ref: '#/components/parameters/Seniority'
        - $ref: '#/components/parameters/Role'
        - $ref: '#/components/parameters/IntelligenceLimit'
      responses:
        '200':
          description: >-
            Ranked skills with posting share, company count, and newly observed
            demand.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopSkillsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    Country:
      name: country
      in: query
      description: Optional ISO 3166-1 alpha-2 country filter.
      schema:
        type: string
        pattern: ^[A-Za-z]{2}$
      example: US
    WorkplaceType:
      name: workplace_type
      in: query
      description: Optional normalized workplace filter.
      schema:
        type: string
        enum:
          - remote
          - hybrid
          - onsite
    Seniority:
      name: seniority
      in: query
      description: Optional normalized seniority filter.
      schema:
        type: string
        enum:
          - intern
          - entry
          - mid
          - senior
          - staff
          - principal
          - executive
    Role:
      name: role
      in: query
      description: Canonical role ID or name from `/v1/taxonomy/roles`.
      schema:
        type: string
        minLength: 1
        maxLength: 160
      example: data-engineer
    IntelligenceLimit:
      name: limit
      in: query
      description: Maximum ranked items to return.
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 20
  schemas:
    TopSkillsResponse:
      allOf:
        - $ref: '#/components/schemas/IntelligenceEnvelope'
        - type: object
          required:
            - postings_analyzed
            - count
            - items
          properties:
            postings_analyzed:
              type: integer
            count:
              type: integer
            items:
              type: array
              items:
                type: object
                required:
                  - rank
                  - id
                  - skill
                  - category
                  - postings
                  - posting_share
                  - company_count
                  - new_postings_7d
                properties:
                  rank:
                    type: integer
                  id:
                    type: string
                    nullable: true
                  skill:
                    type: string
                  category:
                    type: string
                    nullable: true
                  postings:
                    type: integer
                  posting_share:
                    type: number
                  company_count:
                    type: integer
                  new_postings_7d:
                    type: integer
    IntelligenceEnvelope:
      type: object
      required:
        - updated_at
        - filters
      properties:
        updated_at:
          type: string
          format: date-time
          nullable: true
          description: Latest verification time represented by the aggregation.
        filters:
          type: object
          additionalProperties:
            type: string
          description: Normalized filters applied to the aggregation.
    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:
    BadRequest:
      description: Invalid filter or unknown canonical role or skill.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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.

````