Skip to main content

​
API Reference

This section documents every endpoint in the Fribl API. Each page includes request parameters, response schemas, and an interactive playground for testing.

​
Base URL

https://api-service.fribl.co/api/v1

​
Authentication

Most endpoints require the x-api-key header. The Skills endpoints are publicly accessible. See Authentication for details.

​
Endpoint groups

CVs

Analyze, retrieve, update, list, and delete CVs.
  • POST /cvs/analyze — Analyze CVs from text
  • POST /cvs/analyze/files — Analyze CVs from file uploads
  • POST /cvs/status — Check processing status
  • GET /cvs — List all CVs
  • GET /cvs/{id} — Get a CV by ID
  • PUT /cvs/{id} — Update a CV
  • DELETE /cvs/{id} — Delete a CV

Jobs

Analyze, retrieve, update, list, and delete jobs.
  • POST /jobs/analyze — Analyze jobs from text
  • POST /jobs/analyze/files — Analyze jobs from file uploads
  • POST /jobs/status — Check processing status
  • GET /jobs — List all jobs
  • GET /jobs/{id} — Get a job by ID
  • PUT /jobs/{id} — Update a job
  • DELETE /jobs/{id} — Delete a job

Matching

Match CVs against jobs and retrieve results.
  • POST /match — Match CVs to a job
  • GET /match/{jobId} — Get match results

Sourcing

Search and ingest external candidate profiles.
  • POST /sourcing/search — Search candidate profiles
  • POST /sourcing/ingest — Ingest selected profiles

Skills

Search the ESCO skills taxonomy. No authentication required.
  • GET /skills/search — Search for skills by keyword
  • GET /skills/languages — Get available languages

Tokens

Inspect usage-based token balance, history, and pricing.
  • GET /tokens/balance — Current workspace balance
  • GET /tokens/history — Paginated usage ledger
  • GET /tokens/costs — Live per-action price list
Update endpoints require content_language in the request body. Structured skills are returned as hard_skills and soft_skills. The type and relationship fields are static English enums, and relationship uses lowercase canonical values: required, optional, satisfies.

​
Asynchronous processing

CV and job analysis runs asynchronously. After submitting a document, you receive task IDs and must poll the corresponding status endpoint until the status changes to COMPLETED. Keep polling while the status is PENDING. If you poll an unknown ID, the status endpoint returns NOT_FOUND for that item. GET /cvs/{id} and GET /jobs/{id} follow the same vocabulary, but signal in-flight tasks with HTTP 404 + body { "status": "PENDING" }. 
analyze → poll status → retrieve results or match
See the Quickstart for a complete end-to-end example.

​
Response format

Successful responses follow this pattern: 
{
  "message": "Descriptive success message",
  "data": { ... }
}
List endpoints also include length and pagination: 
{
  "message": "...",
  "length": 10,
  "data": [ ... ],
  "pagination": {
    "total": 100,
    "offset": 0,
    "limit": 10,
    "has_more": true
  }
}
Most error responses use: 
{
  "error": "Error description"
}
Update endpoints can also return structured validation details: 
{
  "detail": {
    "message": "Update validation failed."
  }
}
Billable endpoints return 402 with a structured token error when the workspace balance is too low: 
{
  "code": "INSUFFICIENT_TOKENS",
  "message": "Insufficient tokens: have 3, need 10",
  "balance": 3,
  "required": 10
}
See Error Handling for the full list of status codes and Tokens & Billing for pricing and balance management.