# Concepts

Files, jobs, artifacts and credits — the four nouns the whole API is built from, and how they relate.

## Files

A file is bytes you uploaded, plus what Fylane learned by inspecting them. A file arrives `quarantined` and is not processable until validation completes — the type you declared is checked against the type the bytes actually are, and a mismatch is recorded rather than trusted.

## Jobs

A job is one unit of processing. Creating one reserves credits atomically and returns `202`; it never returns a result, because the result may not exist for minutes. Jobs move through `queued`, `running`, then exactly one of `succeeded`, `failed` or `cancelled`.

Jobs are routed by the work they imply, not by a single queue.

| Class | Target p95 | Typical work |
| --- | --- | --- |
| `fast` | under 2 seconds | Thumbnails, resizes, format conversion, inspection |
| `standard` | under 60 seconds | Office to PDF, PDF operations, short OCR |
| `heavy` | minutes | Hundred-page OCR, large extraction runs |

## Artifacts

An artifact is a file a job produced. Artifacts are delivered from `cdn.fylane.dev` behind short-lived URLs that are minted only after an authorisation decision — possession of a URL is never itself the permission.

## Credits

Credits are reserved when a job is accepted and settled when it finishes. A job that would exceed your balance is refused at creation, which is the only point at which refusing is useful. `credits_estimated` is what was held; `credits_charged` is what it actually cost.

> **Rate limit headers are not a billing record**
>
> Gateway throttling protects the service; it does not account for usage. `GET /v1/usage` is the authoritative record, and it is the only thing you should reconcile against.

## Identifiers

Every id is a prefixed, sortable UUIDv7 in Crockford base32 — `job_01JBQ8Z5T7WXK9MNP2RSTVA3C4`. The prefix tells you what it is when it turns up in a log; the encoding makes ids sort by creation time. They are case-sensitive and are never typed by a human, so nothing normalises them.

| Prefix | Resource |
| --- | --- |
| `ups_` | Upload session |
| `file_` | File |
| `job_` | Job |
| `art_` | Artifact |
| `whe_` | Webhook endpoint |
| `req_` | Request — appears in every response and every error |