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
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 in_progress or retrying. If you poll an unknown ID, the status endpoint returns not_found for that item. 
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."
  }
}
See Error Handling for the full list of status codes.