Job Analyze API
POST /api/v1/job/analyze
Use this endpoint when an application needs ranked occupation candidates, supporting evidence, explanations, and decision-support fields from job text.
/api/v1/job/analyze is the highest-context job endpoint. Use it when your product needs to compare candidate occupations, expose skill evidence, show why a match was selected, inspect related occupation context, or route results into review and automation using confidence, trust, uncertainty, ambiguity, and weak-signal fields.
Complete executable examples belong in the AvelinLabs API examples repository.
Base URL: https://api.avelinlabs.com
Authentication
Section titled “Authentication”Requires a runtime API key:
Authorization: Bearer <runtime-api-key>Request Body
Section titled “Request Body”Type: string
Required: Yes
Meaning: Job title or short role label to analyze.
description
Section titled “description”Type: string
Required: No
Meaning: Job description or other skill-bearing text. More complete text can improve the quality of evidence.
Type: boolean
Required: No
Meaning: Optional diagnostic flag. Public integrations should not depend on debug-only fields.
Minimal Request
Section titled “Minimal Request”{ "title": "Data Analyst", "description": "Build dashboards, analyze business metrics, create reports, and communicate insights to stakeholders.", "debug": false}See the public example payload: payloads/job-analyze.json.
Minimal Response
Section titled “Minimal Response”Illustrative beta response snippet:
{ "job_title": "Data Analyst", "confidence": 0.88, "trust_score": 0.84, "confidence_level": "HIGH", "job_signals": ["dashboards", "reporting"], "uncertainty": { "total": 0.185 }, "decision": { "decision": "AUTO_ACCEPT", "reason": "Confidence and uncertainty meet the configured decision threshold." }, "results": [ { "onet_code": "15-2051.01", "title": "Business Intelligence Analysts", "confidence": 0.88, "matching_skills": ["Microsoft Power BI"], "explanation": { "why_match": "The role aligns with dashboarding, reporting, and analytical work." } } ]}See the public example response: responses/job-analyze.example.json.
Top-Level Response Fields
Section titled “Top-Level Response Fields”job_title
Section titled “job_title”Meaning: Echoes or normalizes the job title used for analysis.
model_version
Section titled “model_version”Meaning: Version label for the response-producing model or scoring configuration. Treat as metadata.
confidence
Section titled “confidence”Meaning: Top-level confidence signal for the overall result. Use as decision support, not absolute truth.
confidence_raw
Section titled “confidence_raw”Meaning: Raw or pre-adjusted confidence signal where present. Most clients should prefer confidence and confidence_level.
trust_score
Section titled “trust_score”Meaning: Overall trust-oriented score derived from result strength and quality support.
confidence_level
Section titled “confidence_level”Meaning: Categorical confidence label such as HIGH, intended for display and routing logic.
confidence_band
Section titled “confidence_band”Meaning: Optional beta-era categorical confidence field. Clients should handle it if present and ignore it if absent.
confidence_type
Section titled “confidence_type”Meaning: Describes the semantics of the top-level confidence value.
distribution_type
Section titled “distribution_type”Meaning: Describes how per-result confidence values are represented.
uncertainty
Section titled “uncertainty”Meaning: Object containing uncertainty signals. See output interpretation.
decision
Section titled “decision”Meaning: Optional decision block that can help route results to automation or review.
task_type
Section titled “task_type”Meaning: Broad inferred task or role category when available.
job_signals
Section titled “job_signals”Meaning: Skill, tool, task, or domain signals detected from the input.
inferred_intent
Section titled “inferred_intent”Meaning: Structured intent or archetype information when available. Treat as supporting context.
title_reliability_score
Section titled “title_reliability_score”Meaning: Signal indicating how reliable the title appears as evidence.
onet_families
Section titled “onet_families”Meaning: O*NET family codes associated with the result set.
domain_confidence
Section titled “domain_confidence”Meaning: Signal for how strongly the input appears to fit the supported domain.
domain_grounding
Section titled “domain_grounding”Meaning: Categorical domain support label when present.
domain_grounding_explanation
Section titled “domain_grounding_explanation”Meaning: Human-readable summary of the domain support signal.
domain_is_ambiguous
Section titled “domain_is_ambiguous”Meaning: Indicates whether the domain evidence is ambiguous.
is_ambiguous
Section titled “is_ambiguous”Meaning: Indicates whether the overall result should be treated as ambiguous.
weak_signal_detected
Section titled “weak_signal_detected”Meaning: Indicates that available evidence may be sparse or weak.
weak_signal_reason
Section titled “weak_signal_reason”Meaning: Short reason for weak-signal detection when present.
llm_used and llm_status
Section titled “llm_used and llm_status”Meaning: Optional metadata indicating whether model-assisted reasoning was used. Do not build core workflow logic around these fields.
llm_reasoning
Section titled “llm_reasoning”Meaning: Optional explanation text when available. Treat as supporting narrative, not a contract guarantee.
results
Section titled “results”Meaning: Ranked array of occupation matches.
results[] Fields
Section titled “results[] Fields”onet_code
Section titled “onet_code”Meaning: O*NET occupation code for the candidate result.
onet_family
Section titled “onet_family”Meaning: Broader O*NET family code.
Meaning: Occupation title.
confidence
Section titled “confidence”Meaning: Per-result confidence within the returned ranked set. Interpret relative to other returned candidates.
realism_score
Section titled “realism_score”Meaning: Signal for whether the result is plausible for the input.
quality_score
Section titled “quality_score”Meaning: Aggregate quality signal for the candidate.
quality_breakdown
Section titled “quality_breakdown”Meaning: Additive object of numeric quality components. Clients should ignore unknown keys.
domain_grounding
Section titled “domain_grounding”Meaning: Categorical support for the result within the supported domain.
domain_alignment
Section titled “domain_alignment”Meaning: Categorical alignment signal.
quality_issues
Section titled “quality_issues”Meaning: List of potential quality concerns, if any.
suggested_improvements
Section titled “suggested_improvements”Meaning: Suggestions for improving input quality, if available.
skills
Section titled “skills”Meaning: O*NET 30.3-grounded skill records, typically including skill name, importance, and level.
knowledge
Section titled “knowledge”Meaning: Knowledge-area records associated with the occupation.
abilities
Section titled “abilities”Meaning: Ability records associated with the occupation.
Meaning: Example task statements associated with the occupation.
technologies
Section titled “technologies”Meaning: Technology records associated with the occupation, optionally including demand or hot-technology flags.
matching_skills
Section titled “matching_skills”Meaning: Skills from the input or context that support the match. These may not exactly match O*NET skill labels.
matching_skills_source
Section titled “matching_skills_source”Meaning: Indicates how matching skills were derived, for example from extracted input signals.
related_occupations
Section titled “related_occupations”Meaning: Related occupation suggestions with O*NET codes, titles, tiers, and scores where available.
explanation
Section titled “explanation”Meaning: Structured explanation object.
confidence_explanation
Section titled “confidence_explanation”Meaning: Optional confidence explanation text.
explanation Fields
Section titled “explanation Fields”why_match
Section titled “why_match”Meaning: Human-readable reason the occupation is a match.
key_factors
Section titled “key_factors”Meaning: List of important evidence points.
score_summary
Section titled “score_summary”Meaning: Object with score components such as semantic match, skill match, domain alignment, and signal overlap where available.
Interpretation Notes
Section titled “Interpretation Notes”Use ranked results and confidence fields as decision-support signals. Ambiguous, weak-signal, or low-confidence outputs should generally be reviewed before automation.
Use /job/classify instead when your integration only needs one top O*NET occupation and does not need the ranked candidate list or expanded evidence.
For cross-endpoint guidance, read output interpretation and standard error responses.