Suggest new skills for a theme¶

POST /lexi/api/v1/jobs/suggest_skills

This endpoint implements NB-8044: it lets Lexi suggest new competencies while analyzing an existing job referential, either to identify emerging competencies or to enrich the catalog around a theme such as leadership or languages.

What Lexi sends¶

curl 'http://localhost:8000/lexi/api/v1/jobs/suggest_skills' \
  --header 'X-API-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "jobs": [
    {
      "job_code": "MGR-1",
      "job_title": "Team manager",
      "job_description": "Manages an operational team.",
      "skills": [
        {
          "skill_code": "SK-1",
          "skill_title": "Planning"
        }
      ]
    }
  ],
  "theme": "leadership",
  "outputLanguage": "en",
  "clientContext": "B2B software publisher",
  "skillsNumber": 6
}
JSON

Only job_title is required for each job. Its family, description and existing skills improve suggestion accuracy.

theme is optional. When provided, suggestions focus on that domain, for example "leadership" or "languages". When it is absent or empty, AI Hub suggests broadly relevant or emerging competencies for the job without restricting the result to one domain. This is the emerging-skill discovery use case.

To produce consistent additions, AI Hub first identifies the job's core from its title, then refines its scope with the family and description. Existing skills define what the job already covers. Finally, clientContext adapts the suggestions to explicitly supplied industry, product, service, working environment and constraint information without changing the job or inventing company-specific facts.

skillsNumber sets the target total number of skills for each job under the requested theme. It accepts a value from 1 to 20 and defaults to 8. If a job already contains two skills and the target is six, the endpoint suggests at most four. When the target is already met, no LLM call is made for that job.

Response¶

Existing skills are never modified. Proposed additions are returned separately under suggested_skills:

{
  "jobs": [
    {
      "job_code": "MGR-1",
      "job_title": "Team manager",
      "job_description": "Manages an operational team.",
      "skills": [
        {
          "skill_code": "SK-1",
          "skill_title": "Planning"
        }
      ],
      "suggested_skills": [
        "Frontline leadership",
        "Conflict management",
        "Team coaching",
        "Effective delegation"
      ]
    }
  ]
}

Additional fields received on jobs or skills are preserved in the response. The model is instructed to avoid semantic reformulations of existing skills. Exact textual duplicates of existing skills or other suggestions are also removed while processing the response.

A generation error returns 400 with {"detail":"Error during job skill suggestion"}.

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