> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fribl.co/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for all Fribl API endpoints

# 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](/authentication) for details.

## Endpoint groups

<CardGroup cols={2}>
  <Card title="CVs" icon="file-user">
    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
  </Card>

  <Card title="Jobs" icon="briefcase">
    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
  </Card>

  <Card title="Matching" icon="arrows-rotate">
    Match CVs against jobs and retrieve results.

    * `POST /match` — Match CVs to a job
    * `GET /match/{jobId}` — Get match results
  </Card>

  <Card title="Sourcing" icon="magnifying-glass">
    Search and ingest external candidate profiles.

    * `POST /sourcing/search` — Search candidate profiles
    * `POST /sourcing/ingest` — Ingest selected profiles
  </Card>

  <Card title="Skills" icon="lightbulb">
    Search the ESCO skills taxonomy. No authentication required.

    * `GET /skills/search` — Search for skills by keyword
    * `GET /skills/languages` — Get available languages
  </Card>

  <Card title="Tokens" icon="wallet">
    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
  </Card>
</CardGroup>

<Note>
  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`.
</Note>

## 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](/quickstart) for a complete end-to-end example.

## Response format

Successful responses follow this pattern:

```json theme={null}
{
  "message": "Descriptive success message",
  "data": { ... }
}
```

List endpoints also include `length` and `pagination`:

```json theme={null}
{
  "message": "...",
  "length": 10,
  "data": [ ... ],
  "pagination": {
    "total": 100,
    "offset": 0,
    "limit": 10,
    "has_more": true
  }
}
```

Most error responses use:

```json theme={null}
{
  "error": "Error description"
}
```

Update endpoints can also return structured validation details:

```json theme={null}
{
  "detail": {
    "message": "Update validation failed."
  }
}
```

Billable endpoints return `402` with a structured token error when the workspace balance is too low:

```json theme={null}
{
  "code": "INSUFFICIENT_TOKENS",
  "message": "Insufficient tokens: have 3, need 10",
  "balance": 3,
  "required": 10
}
```

See [Error Handling](/errors) for the full list of status codes and [Tokens & Billing](/tokens) for pricing and balance management.