Skip to content

Generate skill levels

POST /lexi/api/v1/jobs/get_skill_levels

This endpoint runs only the level-generation sub-step used by generate_skills. It does not generate, normalize or filter any skills.

Request from Lexi

curl 'http://localhost:8000/lexi/api/v1/jobs/get_skill_levels' \
  --header 'X-API-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "jobs": [
    {
      "job_code": "DEV-1",
      "job_title": "Developer",
      "job_description": "Designs and maintains platform services.",
      "skills": [
        {
          "skill_code": "SK-1",
          "skill_title": "Python",
          "skill_definition": "Ability to develop robust Python applications in order to deliver reliable software."
        }
      ]
    }
  ],
  "skillLevelScale": 5,
  "clientContext": "Software company"
}
JSON

The complete JSON contract is shown below.

{
  "jobs": [
    {
      "job_code": "DEV-1",
      "job_title": "Developer",
      "job_description": "Designs and maintains platform services.",
      "job_family": "Technology",
      "skills": [
        {
          "skill_code": "SK-1",
          "skill_title": "Python",
          "skill_definition": "Ability to develop robust Python applications in order to deliver reliable software.",
          "skill_group": "TECHNIQUE"
        }
      ]
    }
  ],
  "skillLevelScale": 5,
  "clientContext": "Software company",
  "debug": false
}

skillLevelScale is required and must be 4 or 5. job_code, job_title, skill_code and skill_title are required so that every level can be returned for the correct job/skill pair. job_description and skill_definition are optional. skill_description is also accepted as an input alias for skill_definition. Other fields on jobs and skills are preserved in the response.

Processing logic

The jobs and their skills are passed to the same function as the “Skill level” sub-step of generate_skills, with the same options:

  • group skills by job without merging two codes with the same label;
  • use the client context as the industry;
  • add the job description to the prompt when available;
  • add each skill definition to the prompt only when available;
  • use batch generation with the same concurrency configuration;
  • generate one level per skill, from 1 to skillLevelScale.

Compatible OpenAI mini assigns a categorical level to each indexed job/skill pair, batching up to 400 independent questions per native request. Job/skill identities and input order are preserved, including identical labels with different codes. Industry, job context, supplied definitions and quality rules remain part of the assessment. The fixed OpenAI default resolves the shared mini profile when no configuration is supplied. Unsupported providers, models or choice scales retain the original large structured-generation path. Native refusals, invalid responses and timeouts propagate to the workflow's error boundary; they never become invented levels or trigger generative retries.

In generate_skills, the job description is now passed to this same sub-step when it exists. Skill descriptions are still generated concurrently with levels, so they are not expected in that historical flow.

Response

The response preserves the received jobs and skills and adds required_skill_level:

{
  "jobs": [
    {
      "job_code": "DEV-1",
      "job_title": "Developer",
      "job_description": "Designs and maintains platform services.",
      "job_family": "Technology",
      "skills": [
        {
          "skill_code": "SK-1",
          "skill_title": "Python",
          "skill_definition": "Ability to develop robust Python applications in order to deliver reliable software.",
          "skill_group": "TECHNIQUE",
          "required_skill_level": 4
        }
      ]
    }
  ]
}

Generation errors return 400 with {"detail":"Error during skill level retrieval"}.

The generated lexi HTTP reference is the authoritative source for parameters, schemas, responses and examples.