Occupation API

Occupation endpoints provide the production O*NET 30.3 hybrid candidate shortlist and context for known occupation codes. Lexical retrieval remains the exact safe fallback.

Complete executable examples belong in the AvelinLabs API examples repository. Run the cURL example or Python example with the sample payload, and inspect the serializer-produced response.

Base URL: https://api.avelinlabs.com

Authentication

Requires a runtime API key:

Authorization: Bearer <runtime-api-key>

POST /api/v1/occupation/candidates

Use this endpoint to retrieve an ordered shortlist of plausible occupations for a title and optional sanitized description. It uses local lexical and semantic retrieval when governed hybrid resources are active. It is candidate retrieval for human or downstream review, not job classification or an official mapping.

{
  "title": "Psychiatric Technician",
  "description": "Provides direct care and observes patients in a behavioral health setting.",
  "limit": 1
}

title is required. Supply a sanitized job description when available: description and task evidence may improve candidate ordering, but do not make rank 1 authoritative. limit defaults to 5 and accepts integers from 1 through 10.

{
  "query": {
    "title": "Psychiatric Technician",
    "description_used": true
  },
  "candidates": [
    {
      "rank": 1,
      "onet_code": "29-2053.00",
      "title": "Psychiatric Technicians",
      "relevance_score": 2765.113,
      "match_reasons": [
        "normalized_primary_title_match",
        "complete_occupational_phrase_match",
        "primary_title_token_match",
        "occupational_context_match",
        "role_head_match",
        "description_match",
        "task_match",
        "vector_candidate_expansion"
      ],
      "evidence": {
        "matched_title": "Psychiatric Technicians",
        "title_match_type": "primary",
        "query_role_head": "technician",
        "candidate_role_head": "technician",
        "role_head_agreement": true,
        "description_term_matches": 3,
        "task_term_matches": 5
      }
    }
  ],
  "decision": "candidates_only",
  "mapping_selected": false,
  "taxonomy_version": "30.3",
  "policy": "avelin-onet-hybrid-shortlist-30.3-v1",
  "score_interpretation": "ordering_only_not_probability",
  "attribution": "O*NET Resource Center; U.S. Department of Labor/Employment and Training Administration"
}

mapping_selected is always false. Rank 1 is a suggestion, not an official or authoritative mapping, and relevance_score is useful only for ordering candidates within the current response. It is not a probability or correctness confidence. Ambiguous or compound roles may retain multiple plausible candidates; nonsensical or insufficient input may return an empty list. The endpoint selects and persists no mapping.

When governed hybrid resources are active, policy is avelin-onet-hybrid-shortlist-30.3-v1. If the semantic channel is disabled or unavailable, the exact lexical fallback uses avelin-onet-candidate-retrieval-30.3-v1. Policy identifies the retrieval path only; clients must not treat either value as a correctness signal. Identical requests are deterministic for fixed governed resources.

The local retrieval resources are derived from the official ONET 30.3 database distribution and used under CC BY 4.0. No ONET web service is called at request time. Public responses intentionally exclude embeddings, model lineage, internal retrieval provenance, artifact hashes, local paths, and operational details.

Frozen evaluation note: On the governed evaluation set, lexical top-5 and top-10 were 80% and 89%; hybrid top-5 and top-10 were 89% and 92%; hybrid wrong-family rank 1 was 17%. These measurements are evaluation evidence, not an SLA, correctness guarantee, or permission to select rank 1 automatically.

GET /api/v1/occupation/{onet_code}

Use this endpoint to retrieve a concise occupation summary for a known O*NET code.

Path Parameter: onet_code

Type: string

Required: Yes

Meaning: O*NET occupation code, for example 15-1252.00.

Minimal Response

Illustrative beta response snippet:

{
  "onet_code": "15-1252.00",
  "title": "Software Developers",
  "top_skills": [
    {
      "skill_name": "Programming",
      "importance": 92.5,
      "level": 78.0
    }
  ]
}

See the public example response: responses/occupation.example.json.

Response Field: onet_code

Meaning: O*NET occupation code returned by the lookup.

Response Field: title

Meaning: Occupation title.

Response Field: top_skills

Meaning: Array of high-signal skill records associated with the occupation.

Response Field: top_skills[].skill_name

Meaning: Skill name.

Response Field: top_skills[].importance

Meaning: Relative importance score for the skill.

Response Field: top_skills[].level

Meaning: Relative level score for the skill.

GET /api/v1/occupation/profile/{onet_code}

Use this endpoint when an application needs a richer occupation profile for display, enrichment, or review workflows.

Path Parameter: onet_code

Type: string

Required: Yes

Meaning: O*NET occupation code, for example 15-1252.00.

Minimal Response

Illustrative beta response snippet:

{
  "occupation": {
    "onet_code": "15-1252.00",
    "title": "Software Developers",
    "description": "Research, design, and develop computer and network software or specialized utility programs."
  },
  "skills": [
    {
      "name": "Programming",
      "importance": 92.5,
      "level": 78.0
    }
  ],
  "technologies": [
    {
      "name": "Python",
      "is_hot": true,
      "is_in_demand": true
    }
  ],
  "tasks": ["Develop software systems and applications."]
}

See the public examples repository for occupation examples: AvelinLabs API examples.

Response Field: occupation

Meaning: Main occupation object.

Response Field: occupation.onet_code

Meaning: O*NET occupation code.

Response Field: occupation.title

Meaning: Occupation title.

Response Field: occupation.description

Meaning: Public occupation description where available.

Response Field: skills

Meaning: Skill records with names, importance, and level values.

Response Field: technologies

Meaning: Software/technology records associated with the occupation. The public field name remains technologies for API compatibility.

Response Field: technologies[].name

Meaning: Software or technology name.

Response Field: technologies[].is_hot

Meaning: Indicates whether the software/technology term is marked as hot where available.

Response Field: technologies[].is_in_demand

Meaning: Indicates whether the software/technology term is marked as in demand where available.

Response Field: tasks

Meaning: Task statements associated with the occupation.

Response Field: related_occupations

Meaning: Related occupation records with O*NET codes, titles, and relatedness tiers where available.

Interpretation Notes

Occupation endpoints are useful for candidate selection, enriching UI displays, explaining classification outputs, and adding standardized occupation context to workflows. ONET 30.3 taxonomy fields use ONET Resource Center data under CC BY 4.0 with U.S. Department of Labor/Employment and Training Administration attribution.

For cross-endpoint guidance, read output interpretation and standard error responses.