Skill Gap Identification API

When to use this API

Use this API when you need to know what skills a person is missing for a specific role - for a promotion, an internal move, or a hiring decision.

Send a document, a target role, or both. With a document and a role, the person's skills are matched against the role and the missing ones are returned as gaps. With just a role (no document), the role's expected skills come back as gaps. The response also includes the matched skills, any additional skills detected, and the person's soft skills - each carrying a 1-4 proficiency level.

Results are returned in English by default. Pass an optional language field (e.g. French, Spanish, German, Hindi) to receive them in that language.

Authentication

All requests require a user-scoped API key passed as a bearer token. Generate one in the platform under Settings → API Keys. Keys are prefixed ok_ and expire after 90 days.

Authorization: Bearer ok_xxxxxxxxxxxxxxxxxxxxxxxx

Parameters

Form fields

Request

# Document + role
curl -X POST https://platform.openknowra.ai/api/bff/v1/skill-gap/analyze \
  -H "Authorization: Bearer $OPENKNOWRA_API_KEY" \
  -F "file=@/path/to/resume.pdf" \
  -F "role=Software Engineer" \
  -F "language=English"

# Role only (no document)
curl -X POST https://platform.openknowra.ai/api/bff/v1/skill-gap/analyze \
  -H "Authorization: Bearer $OPENKNOWRA_API_KEY" \
  -F "role=Software Engineer" \
  -F "language=English"

import os
import requests

API_KEY = os.environ["OPENKNOWRA_API_KEY"]
API_URL = "https://platform.openknowra.ai/api/bff/v1/skill-gap/analyze"

with open("./resume.pdf", "rb") as f:
    res = requests.post(
        API_URL,
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": f},
        data={"role": "Software Engineer", "language": "English"},
    )
res.raise_for_status()
data = res.json()
print("Missing skills:", [g["skill"] for g in data["gapSkills"]])

import fs from "fs";

const API_KEY = process.env.OPENKNOWRA_API_KEY!;
const API_URL = "https://platform.openknowra.ai/api/bff/v1/skill-gap/analyze";

const form = new FormData();
form.append("file", new Blob([fs.readFileSync("./resume.pdf")]), "resume.pdf");
form.append("role", "Software Engineer");
form.append("language", "English");

const res = await fetch(API_URL, { method: "POST", headers: { Authorization: `Bearer ${API_KEY}` }, body: form });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data.matchedSkills, data.gapSkills);

Response

200 OK - Every skill list is an array of { skill, level } objects, where level is a 1-4 proficiency (see the table below). Any list with nothing to report comes back as an empty array. role is echoed only when one was provided.

{
  "success": true,
  "role": "Software Engineer",
  "matchedSkills": [
    { "skill": "java", "level": 4 },
    { "skill": "sql", "level": 2 }
  ],
  "additionalSkills": [
    { "skill": "redis", "level": 3 }
  ],
  "gapSkills": [
    { "skill": "Docker", "level": 3 },
    { "skill": "Kubernetes", "level": 3 },
    { "skill": "CI/CD", "level": 2 }
  ],
  "softSkills": [
    { "skill": "leadership", "level": 4 }
  ],
  "gappedSoftSkills": [
    { "skill": "communication", "level": 4 },
    { "skill": "stakeholder management", "level": 3 }
  ],
  "creditsUsed": 35,
  "newBalance": 965
}

Response fields

Proficiency levels

Errors

{
  "error": {
    "code":     "insufficient_credits",
    "required": 25,
    "balance":  10
  }
}