AvelinLabs API Overview

AvelinLabs exposes API-first labor-market and occupation intelligence through public beta APIs. The first documented domain is U.S. labor market intelligence, including job analysis, occupation classification, skill intelligence, market context, and O*NET 30.3-grounded occupation intelligence.

This API section explains the public endpoints and the meaning of common request and response fields. Complete executable examples belong in the AvelinLabs API examples repository.

Controlled Beta Access

The public API endpoint is live, but runtime product endpoints require an active runtime API key. During beta, keys are issued through controlled early-access onboarding.

Documentation and examples are public for evaluation. The platform onboarding snippets below describe the beta account and runtime-key flow for enabled early-access users; they do not imply fully open self-service production access for arbitrary public users.

Base URL

Use the public API base URL for documented runtime requests:

https://api.avelinlabs.com

Platform Onboarding and Authentication

During beta, the platform flow is API-first for users with controlled early access:

1. Register with POST /api/v1/platform/register.
2. Verify email with GET /api/v1/platform/verify-email?token=....
3. Log in with POST /api/v1/platform/login.
4. Create or receive an enabled runtime API key according to the current beta access policy.
5. Use the runtime API key on product endpoints.

Token Types

Management bearer token

Returned by POST /api/v1/platform/login.

Use it for account and API-key management operations such as creating a runtime API key. This token is not accepted on runtime product endpoints.

Authorization: Bearer <management-bearer-token>

Runtime API key

Most runtime product endpoints require a customer runtime API key sent as a bearer token:

Authorization: Bearer <runtime-api-key>

Runtime API keys are required for product endpoints such as job, occupation, and market APIs. During controlled beta, runtime API keys are issued manually to early-access users or enabled through the documented beta platform flow.

The public readiness endpoint, GET /health/ready, does not require authentication.

Platform Endpoint Snippets

Register

POST /api/v1/platform/register

{
  "email": "[email protected]",
  "password": "ChangeMe123!",
  "full_name": "Alex Morgan",
  "company_name": "Example Company"
}

Illustrative beta response snippet:

{
  "status": "pending_verification",
  "message": "Verification email sent",
  "next_step": "Check your inbox and verify your email address before logging in."
}

Verify Email

GET /api/v1/platform/verify-email?token=...

Illustrative beta response snippet:

{
  "status": "verified",
  "beta_access": "activated",
  "message": "Email verified successfully",
  "next_step": "Your Beta access has been activated. You can now log in and create a Runtime API Key."
}

Log In

POST /api/v1/platform/login

{
  "email": "[email protected]",
  "password": "ChangeMe123!"
}

Illustrative beta response snippet:

{
  "access_token": "<management-bearer-token>",
  "token_type": "bearer"
}

Create a Runtime API Key

POST /api/v1/platform/api-keys/create

Authorization: Bearer <management-bearer-token>

{
  "name": "local-development"
}

Illustrative beta response snippet:

{
  "name": "local-development",
  "masked_preview": "avln_sk_...abcd",
  "raw_api_key": "<runtime-api-key>",
  "status": "active"
}

The raw runtime API key is returned once when created through the platform flow. Store it securely before leaving the response.

Endpoint Reference

Which endpoint should I use?

Use POST /api/v1/job/classify when you need one standardized O*NET occupation for job text.

Use POST /api/v1/job/analyze when you need the highest-context response: ranked candidates, skill evidence, explanations, related occupation context, confidence, uncertainty, ambiguity, weak-signal fields, and review or automation routing signals.

Use GET /api/v1/occupation/profile/{onet_code} when your product UI or review workflow needs structured occupation detail for a known O*NET code.

Use GET /api/v1/market/top and GET /api/v1/market/overview when dashboards or enrichment workflows need labor-market context for skills, technologies, demand, and remote-work signals.

Job analysis

POST /api/v1/job/analyze

Returns ranked occupation matches, skill evidence, confidence signals, and explanations for job text.

Read the job analysis reference

Job classification

POST /api/v1/job/classify

Returns the top O*NET 30.3-grounded occupation match and decision-support fields for job text.

Read the job classification reference

Occupation intelligence

GET /api/v1/occupation/{onet_code}

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

Returns concise and detailed occupation intelligence for a known O*NET code.

Read the occupation API reference

Market intelligence

GET /api/v1/market/top

GET /api/v1/market/overview

Returns labor-market signals such as top skills, technologies, term demand, and remote-work context.

Additional public market endpoints are documented for trending skills, trending technologies, and remote-work rates. See the market API reference for the current frontend summary.

Read the market API reference

Readiness

GET /health/ready

Returns public readiness status for traffic checks.

Read the health API reference

Output Guidance

Scores, confidence, uncertainty, matching skills, occupation matches, and explanations are decision-support signals. They should be interpreted in the context of your product workflow and review policy.

Read output interpretation guidance

Standard Error Responses

Runtime API errors preserve a human-readable detail field and may include request metadata that is useful for debugging and support.

Illustrative beta error response:

{
  "detail": "Invalid API key",
  "request_id": "ab12cd34",
  "status_code": 401
}

Error Fields

detail

Meaning: Human-readable error summary.

request_id

Meaning: Request correlation identifier when available. Include this value when requesting support during beta.

status_code

Meaning: HTTP status code associated with the error.

Common Status Codes

400

Invalid request or payload.

401

Missing, invalid, or expired authentication.

403

Authenticated request is not allowed by the current contract, access policy, or enabled endpoint set.

404

Unknown route or unavailable resource. Job analysis and classification may also return a not-found response when no occupation mapping can be produced.

429

Quota, rate, concurrency, or payload limit reached. During beta, these limits may depend on onboarding or contract terms.

500

Unexpected server error.

503

Service is not ready or is temporarily degraded.

Data Handling Basics

Treat submitted job text, descriptions, skill-bearing content, and API outputs as customer data. Avoid submitting secrets, credentials, unnecessary personal data, or content that is not needed for the requested analysis.

Store runtime API keys securely and never commit them to source control. Beta access and usage may be governed by early-access onboarding, quota, or contract terms.

Current Data Domain

AvelinLabs uses structured occupation intelligence and labor-market signals to support classification, matching, scoring, and explanation. The current public documentation focuses on U.S. labor market signals, job-market and skill intelligence, and O*NET 30.3-grounded occupation intelligence.

Outputs should be interpreted as decision-support signals, not exhaustive market totals or absolute truth.

Beta Stability

AvelinLabs is currently in beta / early access. Core public response concepts are intended to remain stable, but additive fields may be introduced. Clients should ignore unknown fields and avoid depending on debug-only fields.

Related Guides

• Getting started
• Output interpretation
• Examples guide