# CV-Transformer API reference

With the CV-Transformer API you can access and manage your data in a programmatic way, using HTTP requests. The structure of the CV-Transformer API is based on [PostgREST v14](https://docs.postgrest.org/en/v14/).

## [Base URL](#base-url)

All endpoints are relative to `https://api.cv-transformer.com/v1`. Every request must be [authenticated](https://www.cv-transformer.com/sv-SE/api-reference/authentication) with an API key, which scopes all data to its organization.

## [OpenAPI spec](#openapi)

The [OpenAPI specification](https://www.cv-transformer.com/openapi.json) describes the same endpoints and resources, to generate a client, import into tools like Postman, or give to an AI agent.

## [Requests](#requests)

Each [core resource](https://www.cv-transformer.com/sv-SE/api-reference/candidates) supports some or all of the following methods:

- `GET /{resource}` lists records. Use [selecting](https://www.cv-transformer.com/sv-SE/api-reference/selecting), [filtering](https://www.cv-transformer.com/sv-SE/api-reference/filtering) and [sorting & pagination](https://www.cv-transformer.com/sv-SE/api-reference/sorting-pagination) to shape the result.
- `POST /{resource}` creates one record, or several when the body is an array.
- `PATCH /{resource}` updates all records matching the filters.
- `DELETE /{resource}` deletes all records matching the filters.

Request bodies are JSON, sent with the `Content-Type: application/json` header. Updates and deletes without filters apply to every record the API key has access to, so always filter, for example on `id=eq.{id}`.

## [Responses](#responses)

Responses are JSON. List responses include a `Content-Range` header with the returned range and the total number of matching records, for example `0-9/42`. Creates, updates and deletes return no body, unless you send the header `Prefer: return=representation`: then they return the affected records.

## [Errors](#errors)

The API uses conventional HTTP status codes:

- `400` The request is malformed, for example an unknown column, an invalid filter, or a body that doesn't match the endpoint's schema.
- `401` The API key is missing or invalid.
- `403` The API key doesn't have the scope the request needs, or no permission for the change.
- `404` The record the endpoint acts on doesn't exist in the API key's organization.
- `409` The request conflicts with existing data, for example a duplicate key.
- `429` The API key made more requests than its [rate limit](https://www.cv-transformer.com/sv-SE/api-reference/rate-limits) allows.
- `5xx` Something went wrong on our side.

Errors have a JSON body following [the PostgREST error format](https://docs.postgrest.org/en/v14/references/errors.html), with a `message`, `details` and `hint`, and for database errors a `code`. Every request, including failed ones, is logged and can be inspected through the [API requests](https://www.cv-transformer.com/sv-SE/api-reference/api_requests) resource.

Example response headers

HTTP

```
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Range: 0-9/42
```

Example error

JSON

```
{
  "code": "PGRST204",
  "details": null,
  "hint": null,
  "message": "Could not find the 'nme' column of 'layouts' in the schema cache"
}
```