> For the complete documentation index, see [llms.txt](https://doc-api.blurit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc-api.blurit.io/api-v2/using-the-api-v2.md).

# Using the API v2

### Workflow

Anonymization can take from a few seconds (small images) to much longer (large videos or ZIP batches). The API therefore exposes two ways to create a job, and two ways to learn when it is done.

#### Sync vs async creation<br>

| <p><br>Synchronous</p> | Asynchronous                                             |                                                    |
| ---------------------- | -------------------------------------------------------- | -------------------------------------------------- |
| Endpoint               | `POST /v2/jobs/sync`                                     | `POST /v2/jobs`                                    |
| Accepts                | Images only, up to 20 MB                                 | Image, video, or ZIP (normal size limits)          |
| HTTP response          | `200 OK` with the finished job (`succeeded` or `failed`) | `202 Accepted` with a queued job                   |
| Typical use            | Small photos, interactive flows                          | Videos, ZIP batches, large images, fire-and-forget |

Under the hood, processing is always asynchronous. The sync endpoint only waits for completion (up to about 30 seconds) so your client can treat a small image as a single request/response. If the image is accepted but does not finish in time, you get `502 EXTERNAL_SERVICE_ERROR` with a `jobId` in `details` — then poll `GET /v2/jobs/{id}` like an async job.

Video, ZIP, and images larger than 20 MB must use `POST /v2/jobs`. The sync endpoint rejects them with an actionable error pointing you to the async route.

#### How to follow job progress

Once a job exists, you can monitor it in two ways:

* Pull mode — periodically call `GET /v2/jobs/{id}` until `status` is `succeeded` or `failed`. While the job is still running, the response includes `retryAfter` (seconds), also mirrored as the `Retry-After` header — wait that long before polling again.
* Push mode — we notify your server of status changes via a webhook you configure in the BlurIt Manager.

Pull and push are alternatives. Neither is mandatory if you only use `POST /v2/jobs/sync` and the call returns a terminal job immediately.

Job statuses: `queued` → `processing` → `succeeded` or `failed`.

***

### Synchronous workflow (small images)

1. Create and wait — `POST /v2/jobs/sync` with the image as `multipart/form-data` (`file` field). The response body is the finished job in `data`.
2. Download — when `data.status` is `succeeded`, call `GET /v2/jobs/{id}/result` using `data.id`. The JSON never embeds download URLs; build the path from the job id.

```mermaid
%%{init: {
  "sequence": {
    "useMaxWidth": false,
    "actorMargin": 150,
    "width": 100,
    "messageMargin": 50,
    "noteMargin": 20,
    "mirrorActors": false
  }
}}%%


sequenceDiagram
    participant C as Your backend
    participant API as BlurIt API v2

    C->>API: POST /v2/jobs/sync (file + options)
    API->>API: Process image (≤ ~30s)
    API-->>C: 200 OK — data.id, status = succeeded
    C->>API: GET /v2/jobs/{id}/result
    API-->>C: 200 OK (anonymized file bytes)

```

### Pull mode workflow (async)

#### 1. Create a job

Send a `POST` request to `/v2/jobs` with the media as `multipart/form-data`. The API returns `202 Accepted` and a unique job id in `data.id`.

#### 2. Check job status

Call `GET /v2/jobs/{id}` and read `data.status`. If the status is `queued` or `processing`, wait `data.retryAfter` seconds (or the `Retry-After` header), then call again.

This step is optional if you rely on webhooks for status updates.

#### 3. Download the processed media

When `data.status` is `succeeded`, download with:

```
GET /v2/jobs/{id}/result
```

Optionally, if you created the job with `generateJsonDetections=true`:

```
GET /v2/jobs/{id}/detections
```

⚠ Important

* In pull mode, step 2 must be repeated until the job is terminal (`succeeded` or `failed`) — even when you only care about failures.
* Do not call `/result` before `succeeded` (you would get `409 JOB_NOT_READY`).
* Results are kept for a limited retention window (default 7 days). After that, downloads return `410 FILE_PURGED`. Download as soon as the job succeeds if you need the file.

```mermaid
%%{init: {
  "sequence": {
    "useMaxWidth": false,
    "actorMargin": 100,
    "width": 220,
    "messageMargin": 50,
    "noteMargin": 20,
    "mirrorActors": false
  }
}}%%
sequenceDiagram
    participant C as Your backend
    participant API as BlurIt API v2

    C->>API: POST /v2/jobs<br/>(file + options)
    API-->>C: 202 Accepted<br/>data.id, status = queued, retryAfter
    loop Until succeeded or failed
        Note over C: Wait retryAfter seconds
        C->>API: GET /v2/jobs/{id}
        API-->>C: data.status (+ retryAfter if still running)
    end
    C->>API: GET /v2/jobs/{id}/result
    API-->>C: 200 OK (anonymized file bytes)

```

### Push mode workflow

Configure a single webhook URL in the BlurIt Manager → Developers → Webhook. When a job status changes, we `POST` an event to your endpoint (including a `Blurit-Webhook-Token` header you must verify).

Typical flow:

1. Create the job with `POST /v2/jobs` (same as pull mode).
2. Wait for a `job.succeeded` or `job.failed` event on your webhook.
3. Download with `GET /v2/jobs/{id}/result` using the job id from the event payload.

For payload shape, retries, and security, see the Webhook section.

```mermaid
sequenceDiagram
    participant C as Your backend
    participant API as BlurIt API v2
    participant WH as Your webhook

    C->>API: POST /v2/jobs
    API-->>C: 202 Accepted (data.id)
    API->>WH: job.queued / job.processing
    API->>WH: job.succeeded (full Job in data)
    WH-->>API: 2xx
    C->>API: GET /v2/jobs/{id}/result
    API-->>C: 200 OK (anonymized file bytes)
```

### Supported file formats

The formats available to your account are returned by `GET /v2/account` in `data.supportedFormats` (they can vary by plan — e.g. a trial may be image-only). Typically:

Images

* JPEG / JPG
* PNG
* WEBP
* BMP
* TIFF
* GIF
* HEIC / HEIF

Videos

* MP4
* MOV
* MKV
* AVI
* M4V

Archives

* ZIP containing supported image or video files

For the authoritative MIME list for your key, always prefer `GET /v2/account`.

### Limitations

* Sync endpoint (`POST /v2/jobs/sync`): images only, maximum 20 MB, waits up to \~30 seconds.
* Async endpoint (`POST /v2/jobs`): file size must not exceed 8 GB. For ZIP files, the 8 GB limit applies to the archive itself (including all files inside).
* Source and result files are retained for a limited period (default 7 days after completion), then purged automatically.
* Job creation is rate-limited per API key (`X-RateLimit-*` headers; see `GET /v2/account` → `rateLimit`).
