Public API

Career pathways

A career pathway is a personalised, time-phased learning roadmap that takes a candidate from the skills they have today to job-readiness for a target role. Nanaade builds it from the role and current market skill demand — no academic curriculum is required or accepted — so it works for career switchers, self-taught developers and graduates alike.

Generation takes one to two minutes, so the endpoint is asynchronous: you submit the request, then either poll for the result or receive it through a webhook.

Generate

Scope pathways:generate · 3 credits (refunded if generation fails).

curl https://backend.nanaade.ai/v1/career-pathways/generate \
  -H "Authorization: Bearer $NANAADE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cand_839210-devops-2026-09" \
  -d '{
    "external_candidate_id": "cand_839210",
    "target_role": { "title": "Cloud DevOps Engineer" },
    "current_role": "Junior Web Developer",
    "current_skills": ["Linux Basics", "JavaScript", { "name": "Docker", "level": "beginner" }, "Git"],
    "education": { "level": "bachelor", "field": "Computer Science" },
    "weekly_hours_available": 10,
    "country": "Nigeria"
  }'

Field	Required	Notes
`target_role.title`	yes	The role the candidate is working towards. `industry` and `description` are optional context.
`current_skills`	no	Strings, or `{ "name", "level" }` with level `beginner`, `intermediate` or `advanced`. A skill without a level counts as intermediate. Synonyms are understood ("JS" is JavaScript).
`current_role`, `education`, `country`	no	Improve the assessment and market context.
`weekly_hours_available`	no	Sizes the phases: fewer hours means a longer plan, never fewer skills.
`external_candidate_id`	no	Lets you list pathways per candidate and erase them with `DELETE /candidates/{id}`.
`options.include_resources`	no	Default `true`. Attaches one free learning resource per focus skill.

Response 202:

{ "pathway_id": "cp_6aad2fcaf6b3db4150e2b73a", "status": "queued", "poll_url": "/v1/career-pathways/cp_6aad2fcaf6b3db4150e2b73a", "estimated_seconds": 90 }

Retrieve

Scope pathways:read · free. GET /career-pathways/{pathway_id} returns the same object at every stage; status moves through queued → processing → completed (or failed). Poll every 10–15 seconds, or subscribe to pathway.completed and pathway.failed to be told instead.

The completed resource:

{
  "pathway_id": "cp_6aad2fcaf6b3db4150e2b73a",
  "status": "completed",
  "target_role": { "title": "Cloud DevOps Engineer" },
  "readiness_score": 13,
  "skill_checklist": [
    { "skill_id": "aws-services", "name": "AWS Services", "group": "technical", "importance": "core", "current_level": "none" },
    { "skill_id": "docker", "name": "Docker", "group": "technical", "importance": "core", "current_level": "beginner" },
    { "skill_id": "git", "name": "Git", "group": "tools", "importance": "core", "current_level": "intermediate" }
  ],
  "diagnosis": {
    "readiness_summary": "You have a foundational understanding of Git and Linux…",
    "strengths": ["Git", "Linux Administration", "Docker"],
    "priority_gaps": ["AWS Services", "Terraform", "CI/CD Principles"]
  },
  "roadmap": {
    "summary": "This roadmap takes you from foundational Git, Linux and Docker to a Cloud DevOps profile…",
    "total_months": 8,
    "phases": [
      {
        "phase": 1, "title": "Cloud & Container Foundations", "month_start": 1, "month_end": 2,
        "focus": ["AWS Services", "Docker"],
        "milestones": ["Deploy a containerised app to an EC2 instance"],
        "actions": [{ "type": "learn", "title": "AWS core services", "description": "EC2, S3, IAM, VPC basics.", "priority": "high" }],
        "resources": [{ "focus": "AWS Services", "title": "AWS Basics for Beginners", "url": "https://…", "platform": "YouTube", "found": true }]
      }
    ]
  }
}

readiness_score (0–100) weights core skills highest.
skill_checklist is the role's market checklist with the candidate's current_level on each item.
roadmap.phases are contiguous month ranges starting at month 1. Each phase names the 2–4 skills to focus on, verifiable milestones, and actions typed learn, build, practice, network or certify.

GET /career-pathways?external_candidate_id=… lists a candidate's pathways as summaries.

Failures

If generation fails after retries the pathway ends in status: "failed" with an error object, the credits are returned, and a pathway.failed event is sent. Submitting again with a new Idempotency-Key starts a fresh attempt.