Visier Skills Intelligence Engine API

openapi: "3.0.1"
info:
  title: "Skills Intelligence Engine API"
  description: |
    Everything you need to power skills and turn them into actions.
  license:
    name: "Apache License, Version 2.0"
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: "1.0.0"
tags:
  - name: Jobs Library
    description: |
      Access over 3,300 standard jobs and get complete details in 27 languages, such as alternative titles, descriptions, and skills.
  - name: Skills Library
    description: |
      Access over 14,000 skills and get complete skill details in 27 languages, such as alternative titles, descriptions, and hierarchies.
paths:
  /v1/jobs/{id}:
    get:
      summary: Get job details by ID
      tags: [Jobs Library]
      operationId: "GetJob"
      description: |
        If you know the ID of a job, use this endpoint to retrieve information such as display name, description, Automation Index, Remote Work Index, alternative names, and skills.
      parameters:
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: |
            The ID of the job to retrieve details for.
        - name: "Accept-Language"
          in: "header"
          schema:
            type: "string"
          description: |
            Allows you to specify if you want the output to be in one of the accepted languages.

            Format: **ISO 639-1** language code. For a list of supported languages, see "Supported Languages" in the Skills Intelligence Engine API documentation.

            If no value is specified, the response language is English.
      responses:
        "200":
          description: |
            Details of the requested job.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "400":
          description: |
            The API request failed given the parameters provided, such as missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: |
            An unexpected exception occurred on the server.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "504":
          description: |
            The server is taking too long to respond and the request timed out.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
      x-amazon-apigateway-integration:
        type: "aws_proxy"
        credentials: "${apigateway_role}"
        httpMethod: "POST"
        uri: "${lambda-get-job-arn}"
      security:
        - api_key: []
  /v1/jobs:
    get:
      summary: Retrieve a list of jobs
      tags: [Jobs Library]
      operationId: "ListJobs"
      description: |
        Use this endpoint to retrieve all the jobs in Visier's Jobs Library.
      parameters:
        - name: "Accept-Language"
          in: "header"
          schema:
            type: "string"
          description: |
            Allows you to specify if you want the output to be in one of the accepted languages.

            Format: **ISO 639-1** language code. For a list of supported languages, see "Supported Languages" in the Skills Intelligence Engine API documentation.

            If no value is specified, the response language is English.
      responses:
        "200":
          description: |
            List of jobs.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobList"
        "400":
          description: |
            The API request failed given the parameters provided, such as missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: |
            An unexpected exception occurred on the server.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "504":
          description: |
            The server is taking too long to respond and the request timed out.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
      x-amazon-apigateway-integration:
        type: "aws_proxy"
        credentials: "${apigateway_role}"
        httpMethod: "POST"
        uri: "${lambda-list-jobs-arn}"
      security:
        - api_key: []
  /v1/jobs/search:
    get:
      summary: Search jobs
      tags: [Jobs Library]
      operationId: "SearchJob"
      description: |
        Retrieve a list of jobs that match a specified search term.
      parameters:
        - name: "term"
          in: "query"
          required: true
          schema:
            type: "string"
          description: |
            The term to search for. The search term must be URL encoded and the minimum length is 3 characters.
        - name: "Accept-Language"
          in: "header"
          schema:
            type: "string"
          description: |
            Allows you to specify if you want the output to be in one of the accepted languages.

            Format: **ISO 639-1** language code. For a list of supported languages, see "Supported Languages" in the Skills Intelligence Engine API documentation.

            If no value is specified, the response language is English.
      responses:
        "200":
          description: |
            List of jobs matching the search term.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobList"
        "400":
          description: |
            The API request failed given the parameters provided, such as missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: |
            An unexpected exception occurred on the server.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "504":
          description: |
            The server is taking too long to respond and the request timed out.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
      x-amazon-apigateway-integration:
        type: "aws_proxy"
        credentials: "${apigateway_role}"
        httpMethod: "POST"
        uri: "${lambda-search-job-arn}"
      security:
        - api_key: []
  /v1/jobs/standardize:
    post:
      summary: Standardize custom job titles
      tags: [Jobs Library]
      operationId: "StandardizeJobs"
      description: |
        Find the top standardized job matches for any custom job title and optional NAICS code.
      requestBody:
        description: |
          The custom job titles that you want to retrieve standardized jobs for and the optional NAICS code to retrieve industry specific jobs.

          The minimum length is 3 characters and the maximum length is 100 characters. You can submit up to 10 custom job titles per request.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JobStandardizationInputSkills"
        required: true
      responses:
        "200":
          description: |
            The top standardized job matches for each custom job title.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobStandardizationOutputSkills"
        "400":
          description: |
            The API request failed given the parameters provided, such as missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: |
            An unexpected exception occurred on the server.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "504":
          description: |
            The server is taking too long to respond and the request timed out.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
      x-amazon-apigateway-integration:
        credentials: "${apigateway_role}"
        httpMethod: "POST"
        uri: "${lambda-standardize-job-arn}"
        type: "aws_proxy"
      security:
        - api_key: []
  /v1/skills/{id}:
    get:
      summary: Get skill details by ID
      tags: [Skills Library]
      operationId: "GetSkill"
      description: |
        If you know the ID of a skill, use this endpoint to retrieve information such as display name, description, Automation Index, Remote Work Index, and alternative names.
      parameters:
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: |
            The ID of the skill to retrieve details for.
        - name: "Accept-Language"
          in: "header"
          schema:
            type: "string"
          description: |
            Allows you to specify if you want the output to be in one of the accepted languages.

            Format: **ISO 639-1** language code. For a list of supported languages, see "Supported Languages" in the Skills Intelligence Engine API documentation.

            If no value is specified, the response language is English.
      responses:
        "200":
          description: |
            Details of the requested skill.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Skill"
        "400":
          description: |
            The API request failed given the parameters provided, such as missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: |
            An unexpected exception occurred on the server.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "504":
          description: |
            The server is taking too long to respond and the request timed out.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
      x-amazon-apigateway-integration:
        type: "aws_proxy"
        credentials: "${apigateway_role}"
        httpMethod: "POST"
        uri: "${lambda-get-skill-arn}"
      security:
        - api_key: []
  /v1/skills:
    get:
      summary: Retrieve a list of skills
      tags: [Skills Library]
      operationId: "ListSkills"
      description: |
        Use this endpoint to retrieve all skills in Visier's Skills Library.
      parameters:
        - name: "skillGroupId"
          in: "query"
          schema:
            type: "string"
          description: |
            Filter only skills that belong to a certain skill group.
        - name: "skillCategoryId"
          in: "query"
          schema:
            type: "string"
          description: |
            Filter only skills that belong to a certain skill category.
        - name: "Accept-Language"
          in: "header"
          schema:
            type: "string"
          description: |
            Allows you to specify if you want the output to be in one of the accepted languages.

            Format: **ISO 639-1** language code. For a list of supported languages, see "Supported Languages" in the Skills Intelligence Engine API documentation.

            If no value is specified, the response language is English.
      responses:
        "200":
          description: |
            List of skills.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SkillList"
        "400":
          description: |
            The API request failed given the parameters provided, such as missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: |
            An unexpected exception occurred on the server.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "504":
          description: |
            The server is taking too long to respond and the request timed out.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
      x-amazon-apigateway-integration:
        type: "aws_proxy"
        credentials: "${apigateway_role}"
        httpMethod: "POST"
        uri: "${lambda-list-skills-arn}"
      security:
        - api_key: []
  /v1/skills/search:
    get:
      summary: Search skills
      tags: [Skills Library]
      operationId: "SearchSkill"
      description: |
        Retrieve a list of skills that match a specified search term.
      parameters:
        - name: "term"
          in: "query"
          required: true
          schema:
            type: "string"
          description: |
            The term to search for. The search term must be URL encoded and the minimum length is 3 characters.
        - name: "Accept-Language"
          in: "header"
          schema:
            type: "string"
          description: |
            Allows you to specify if you want the output to be in one of the accepted languages.

            Format: **ISO 639-1** language code. For a list of supported languages, see "Supported Languages" in the Skills Intelligence Engine API documentation.

            If no value is specified, the response language is English.
      responses:
        "200":
          description: |
            List of skills matching the search term.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SkillList"
        "400":
          description: |
            The API request failed given the parameters provided, such as missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: |
            An unexpected exception occurred on the server.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "504":
          description: |
            The server is taking too long to respond and the request timed out.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
      x-amazon-apigateway-integration:
        type: "aws_proxy"
        credentials: "${apigateway_role}"
        httpMethod: "POST"
        uri: "${lambda-search-skill-arn}"
      security:
        - api_key: []
  /v1/skills/extract:
    post:
      summary: Extract skills from text
      tags: [Skills Library]
      operationId: "ExtractSkills"
      description: |
        Extract the relevant skills from text such as job descriptions and course outlines.
      parameters:
        - name: "Accept-Language"
          in: "header"
          schema:
            type: "string"
          description: |
            Allows you to specify if you want the output to be in one of the accepted languages.

            Format: **ISO 639-1** language code. For a list of supported languages, see "Supported Languages" in the Skills Intelligence Engine API documentation.

            If no value is specified, the response language is English.
      requestBody:
        description: |
          The text to extract skills from.

          The minimum length is 4 characters and the maximum length is 7500 characters.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SkillExtractionInput"
      responses:
        "200":
          description: |
            List of skills extracted from the text.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SkillExtractionOutput"
        "400":
          description: |
            The API request failed given the parameters provided, such as missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: |
            An unexpected exception occurred on the server.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "504":
          description: |
            The server is taking too long to respond and the request timed out.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
      x-amazon-apigateway-integration:
        type: "aws_proxy"
        credentials: "${apigateway_role}"
        httpMethod: "POST"
        uri: "${lambda-extract-skills-arn}"
      security:
        - api_key: []
  /v1/skills/match:
    post:
      summary: Match a skill set to a group of skill sets (targets)
      tags: [Skills Library]
      operationId: "MatchSkills"
      description: |
        Find the best match between a skill set and a group of skill sets (targets). The response returns a ranking of the targets with the best match appearing at the top of the list.
      requestBody:
        description: |
          The skill set and the group of skill sets (targets) to be matched. The skills included in each skill set are entered in the following format [skill_id, score]. The score represents how prevalent the skill was in the source and is used as a weighting factor when determining the best match.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SkillMatchInput"
      responses:
        "200":
          description: |
            Ranked list of skill sets (targets) with the best match appearing at the top of the list. The integer value indicates the position of the target in the request body.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SkillMatchOutput"
        "400":
          description: |
            The API request failed given the parameters provided, such as missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: |
            An unexpected exception occurred on the server.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "504":
          description: |
            The server is taking too long to respond and the request timed out.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
      x-amazon-apigateway-integration:
        type: "aws_proxy"
        credentials: "${apigateway_role}"
        httpMethod: "POST"
        uri: "${lambda-match-skills-arn}"
      security:
        - api_key: []
  /v1/skill-groups/{id}:
    get:
      summary: Get skill group details by ID
      tags: [Skills Library]
      operationId: "GetSkillGroup"
      description: |
        If you know the ID of a skill group, use this endpoint to retrieve information such as display name, description, Automation Index, Remote Work Index, and alternative names.
      parameters:
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: |
            The ID of the skill group to retrieve details for.
        - name: "Accept-Language"
          in: "header"
          schema:
            type: "string"
          description: |
            Allows you to specify if you want the output to be in one of the accepted languages.

            Format: **ISO 639-1** language code. For a list of supported languages, see "Supported Languages" in the Skills Intelligence Engine API documentation.

            If no value is specified, the response language is English.
      responses:
        "200":
          description: |
            Details of the requested skill group.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SkillGroup"
        "400":
          description: |
            The API request failed given the parameters provided, such as missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: |
            An unexpected exception occurred on the server.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "504":
          description: |
            The server is taking too long to respond and the request timed out.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
      x-amazon-apigateway-integration:
        type: "aws_proxy"
        credentials: "${apigateway_role}"
        httpMethod: "POST"
        uri: "${lambda-get-meta-skill-arn}"
      security:
        - api_key: []
  /v1/skill-groups:
    get:
      summary: Retrieve a list of skill groups
      tags: [Skills Library]
      operationId: "ListSkillGroups"
      description: |
        Use this endpoint to retrieve all skill groups in Visier's Skills Library.
      parameters:
        - name: "skillCategoryId"
          in: "query"
          schema:
            type: "string"
          description: |
            Filter only skills that belong to a certain skill category.
        - name: "Accept-Language"
          in: "header"
          schema:
            type: "string"
          description: |
            Allows you to specify if you want the output to be in one of the accepted languages.

            Format: **ISO 639-1** language code. For a list of supported languages, see "Supported Languages" in the Skills Intelligence Engine API documentation.

            If no value is specified, the response language is English.
      responses:
        "200":
          description: |
            List of skill groups.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SkillGroupList"
        "400":
          description: |
            The API request failed given the parameters provided, such as missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: |
            An unexpected exception occurred on the server.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "504":
          description: |
            The server is taking too long to respond and the request timed out.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
      x-amazon-apigateway-integration:
        type: "aws_proxy"
        credentials: "${apigateway_role}"
        httpMethod: "POST"
        uri: "${lambda-list-meta-skills-arn}"
      security:
        - api_key: []
  /v1/skill-categories/{id}:
    get:
      summary: Get skill category details by ID
      tags: [Skills Library]
      operationId: "GetSkillCategory"
      description: |
        If you know the ID of a skill category, use this endpoint to retrieve information such as display name, description, Automation Index, Remote Work Index, and alternative names.
      parameters:
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: |
            The ID of the skill category to retrieve details for.
        - name: "Accept-Language"
          in: "header"
          schema:
            type: "string"
          description: |
            Allows you to specify if you want the output to be in one of the accepted languages.

            Format: **ISO 639-1** language code. For a list of supported languages, see "Supported Languages" in the Skills Intelligence Engine API documentation.

            If no value is specified, the response language is English.
      responses:
        "200":
          description: |
            Details of the requested skill category.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SkillCategory"
        "400":
          description: |
            The API request failed given the parameters provided, such as missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: |
            An unexpected exception occurred on the server.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "504":
          description: |
            The server is taking too long to respond and the request timed out.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
      x-amazon-apigateway-integration:
        type: "aws_proxy"
        credentials: "${apigateway_role}"
        httpMethod: "POST"
        uri: "${lambda-get-super-skill-arn}"
      security:
        - api_key: []
  /v1/skill-categories:
    get:
      summary: Retrieve a list of skill categories
      tags: [Skills Library]
      operationId: "ListSkillCategories"
      description: |
        Use this endpoint to retrieve all skill categories in Visier's Skills Library.
      parameters:
        - name: "Accept-Language"
          in: "header"
          schema:
            type: "string"
          description: |
            Allows you to specify if you want the output to be in one of the accepted languages.

            Format: **ISO 639-1** language code. For a list of supported languages, see "Supported Languages" in the Skills Intelligence Engine API documentation.

            If no value is specified, the response language is English.
      responses:
        "200":
          description: |
            List of skill categories.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SkillCategoryList"
        "400":
          description: |
            The API request failed given the parameters provided, such as missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: |
            An unexpected exception occurred on the server.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "504":
          description: |
            The server is taking too long to respond and the request timed out.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
      x-amazon-apigateway-integration:
        type: "aws_proxy"
        credentials: "${apigateway_role}"
        httpMethod: "POST"
        uri: "${lambda-list-super-skills-arn}"
      security:
        - api_key: []
components:
  securitySchemes:
    api_key:
      type: "apiKey"
      in: "header"
      name: "x-api-key"
      x-amazon-apigateway-api-key-source: "HEADER"
  schemas:
    Job:
      description: |
        Details describing a job.
      type: "object"
      properties:
        id:
          type: "string"
          description: |
            The unique ID of the job.
        name:
          type: "string"
          description: |
            The localized display name of the job.
        description:
          type: "string"
          description: |
            The localized description of the job.
        iscoCode:
          type: "string"
          description: |
            The International Standard Classification of Occupations (ISCO) code of the job.

            This field will be omitted if the job is not associated with an ISCO code.
        socCode:
          type: "string"
          description: |
            The Standard Occupational Classification (SOC) code of the job.

            This field will be omitted if the job is not associated with a SOC code.
        alternativeTitles:
          type: "array"
          items:
            type: "string"
          description: |
            List of alternative localized names for this job.
        essentialSkills:
          type: "array"
          items:
            $ref: "#/components/schemas/Skill"
          description: |
            List of essential skills for this job.
        optionalSkills:
          type: "array"
          items:
            $ref: "#/components/schemas/Skill"
          description: |
            List of optional skills for this job.
        remoteIndex:
          type: "number"
          description: |
            The Remote Index represents how readily a job can be done through remote work. The index ranges from 0 to 100, where a value of 100 means the job can be done entirely remotely.

            This field will be omitted if remotability is not applicable to the job.
        automationIndex:
          type: "integer"
          description: |
            The Automation Index represents how readily a job can be automated. The index ranges from 0 to 100, where a value of 100 means the job is completely automatable.

            This field will be omitted if automation is not applicable to the job.
      required:
        - "id"
        - "name"
        - "description"
        - "alternativeTitles"
        - "essentialSkills"
        - "optionalSkills"
    JobList:
      type: "array"
      items:
        type: "object"
        title: "JobEntry"
        properties:
          id:
            type: "string"
            description: |
              The unique ID of the job.
          name:
            type: "string"
            description: |
              The localized display name of the job.
          description:
            type: "string"
            description: |
              The localized description of the job.
        required:
          - id
          - name
          - description
    JobStandardizationInputSkills:
      description: |
        The custom job titles to standardize.
      type: "object"
      properties:
        jobs:
          type: "array"
          items:
            type: "string"
        naicsCode:
          type: "string"
          description: |
            The North American Industry Classification System (NAICS) code.

            If `naicsCode` is provided, the most relevant job titles associated with the naicsCode are returned first.
      required:
        - "jobs"
    JobStandardizationOutputSkills:
      type: "array"
      items:
        title: OutputEntry
        type: object
        properties:
          job:
            type: "string"
            description: |
              The custom job title input.
          matches:
            type: array
            description: |
              The top standardized job matches.
            items:
              type: object
              properties:
                id:
                  type: "string"
                  description: |
                    The unique ID of the job.
                name:
                  type: "string"
                  description: |
                    The localized display name of the job.
                description:
                  type: "string"
                  description: |
                    The localized description of the job.
                score:
                  type: "integer"
                  description: |
                    The score representing the confidence level of 

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/visier/refs/heads/main/openapi/visier-skills-intelligence-engine-openapi.yaml