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

# Skill profile

> Inspect one canonical skill across roles, companies, countries, and workplace types.



## OpenAPI

````yaml jobs-api/openapi.json GET /v1/skills/{skill}
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/skills/{skill}:
    get:
      summary: Profile one skill
      description: >-
        Profiles one canonical skill across active postings, roles, companies,
        countries, and workplace types.
      operationId: getSkillProfile
      parameters:
        - name: skill
          in: path
          required: true
          description: Canonical skill ID or name from `/v1/taxonomy/skills`.
          schema:
            type: string
            minLength: 1
            maxLength: 160
          example: python
        - $ref: '#/components/parameters/Country'
        - $ref: '#/components/parameters/WorkplaceType'
        - $ref: '#/components/parameters/Seniority'
      responses:
        '200':
          description: Skill demand and its market distributions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillProfileResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '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
  schemas:
    SkillProfileResponse:
      allOf:
        - $ref: '#/components/schemas/IntelligenceEnvelope'
        - type: object
          required:
            - skill
            - market
            - workplace
            - roles
            - companies
            - countries
          properties:
            skill:
              $ref: '#/components/schemas/PublicSkill'
            market:
              type: object
              required:
                - eligible_postings
                - matching_postings
                - posting_share
                - companies
                - newly_observed_7d
              properties:
                eligible_postings:
                  type: integer
                matching_postings:
                  type: integer
                posting_share:
                  type: number
                companies:
                  type: integer
                newly_observed_7d:
                  type: integer
            workplace:
              $ref: '#/components/schemas/DistributionRows'
            roles:
              type: array
              items:
                $ref: '#/components/schemas/RoleDistributionRow'
            companies:
              $ref: '#/components/schemas/DistributionRows'
            countries:
              $ref: '#/components/schemas/DistributionRows'
    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.
    PublicSkill:
      type: object
      required:
        - id
        - name
        - category
      properties:
        id:
          type: string
        name:
          type: string
        category:
          type: string
    DistributionRows:
      type: array
      items:
        type: object
        required:
          - value
          - postings
          - share
        properties:
          value:
            type: string
          postings:
            type: integer
          share:
            type: number
    RoleDistributionRow:
      allOf:
        - $ref: '#/components/schemas/PublicRole'
        - type: object
          required:
            - postings
            - share
          properties:
            postings:
              type: integer
            share:
              type: number
    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
    PublicRole:
      type: object
      required:
        - id
        - name
        - sector
      properties:
        id:
          type: string
        name:
          type: string
        sector:
          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'
    NotFound:
      description: The requested canonical resource was not found.
      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.

````