Workforce Intelligence API

Avelin’s API is the developer destination for workforce decision support. Use it after the conceptual model on the Workforce Decision Layer.

The current API contract is documented for Runtime and platform endpoints, and outputs are decision-support oriented: explanation, confidence, uncertainty, review guidance, and provenance-aware traceability.

The machine-readable OpenAPI 3.1 contract is available at https://api.avelinlabs.com/openapi.json. Runtime product endpoints use Authorization: Bearer <runtime-api-key>; the management bearer token returned by login is reserved for platform account and key-management operations.

Use the API when you need machine-readable capability outputs for hiring intake, workforce planning, role calibration, and governed review pipelines.

Link to implementation flow

If you are first deciding where this fits in Avelin, start with the Decision Layer page.
See the Input-to-Output Flow for the end-to-end processing model.
If you are implementing authentication, quotas, and runtime key flows, start at Getting Started.
For applied decision patterns, read Evidence-Based Workforce Decisions.

Overview

The public endpoint base for Runtime requests is:

https://api.avelinlabs.com

Avelin follows a single-source API model: shared workforce intelligence, optional customer context via Customer Grounding, and structured decision outputs.

Identity and onboarding

POST /api/v1/platform/register
GET /api/v1/platform/verify-email?token=...
POST /api/v1/platform/login
POST /api/v1/platform/api-keys/create

Platform management uses a separate bearer token from Runtime API Keys used on product endpoints.

Endpoint groups (current verified surface)

Job Intelligence

POST /api/v1/job/analyze
- Ranked occupation candidates,
- skill evidence,
- ambiguity and weak-signal fields,
- confidence and uncertainty signals,
- explanations and review guidance.
- Read job analysis reference
POST /api/v1/job/classify
- Top occupation alignment for job text,
- structured decision-support fields.
- Read job classification reference

Occupation Intelligence

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

Returns the deterministic O*NET 30.3 hybrid candidate shortlist, its exact lexical fallback when governed semantic resources are unavailable, detailed occupation metadata, and related structured intelligence. Candidate search always keeps mapping_selected=false; rank 1 is not a classification or official mapping. See Occupation API.

Workforce Evidence Packs

GET /api/v1/workforce/capabilities
GET /api/v1/workforce/occupations
GET /api/v1/workforce/occupations/{soc_code}
POST /api/v1/workforce/evidence-packs
GET /api/v1/workforce/evidence-packs/{evidence_pack_id}
GET /api/v1/workforce/evidence-packs/{evidence_pack_id}/report

The production-live controlled-beta service packages approved OEWS occupation evidence, separate Census QWI industry evidence, and governed O*NET 30.3 reference data into deterministic account-scoped JSON and standalone HTML. The approved public boundary is currently U.S./Connecticut and remains entitlement-dependent. See the Workforce Evidence Pack API.

Market Intelligence

GET /api/v1/market/top
GET /api/v1/market/overview

Labor-market context used for role and skill interpretation. See Market API.

Customer Grounding

Customer Grounding lets you add tenant-scoped sources and request grounded role analysis where your contract includes it.

GET /api/v1/grounding/capabilities
POST /api/v1/grounding/sources
POST /api/v1/grounding/sources/{source_id}/ingest-text
POST /api/v1/grounding/sources/{source_id}/ingest-file
POST /api/v1/grounding/role-intelligence/reports
GET /api/v1/grounding/traces/{trace_id}

See Customer Grounding.

Use include_passport=true on POST /api/v1/grounding/role-intelligence/reports to add a bounded passport object to the same response.

If include_passport is omitted or false, the historical response shape is preserved.

For optional Passport schema context, see Decision Passport.

Operational integration

MCP

Avelin supports customer-operated MCP adapter usage over authenticated Runtime API flows. MCP does not replace the product semantics.

Examples and interpretation

Public executable examples remain in the AvelinLabs API examples repository.

Use API examples and output interpretation guidance to integrate outputs safely.

Readiness and errors

Health signals

GET /health/live and GET /health/ready remain unauthenticated. Liveness only confirms that the process answers; readiness indicates whether the public API can receive governed customer traffic.

Standard error responses

Protected operations are authenticated by middleware before their endpoint handler runs. For example, PROD returns this shape when the Runtime bearer header is missing (the observed request identifier is replaced here):

{
  "detail": "Missing authorization",
  "request_id": "<request-id>",
  "status_code": 401,
  "error_code": "missing_authorization"
}

The current OpenAPI contract identifies protected operations with the RuntimeApiKey security scheme, but does not yet declare the middleware 401 response on those operations. Treat this as observed Runtime behavior, not as a claim that 401 is fully modeled in OpenAPI. Preserve request_id for support and branch on stable error_code values where appropriate. See the invalid-key executable example and its sanitized response fixture.

See health and response fields for field-level usage and metrics guidance.

Practical limits and scope

O*NET is the current occupational foundation.
The current phase supports free-tier self-service beta with documented contracts, quotas, and customer-grounding limits.
Avelin does not claim placement automation, hiring decisions, or ATS-like execution.