# Jobs API

Jobs are the core async unit in the Redact PDF AI API.

Each job can include one or many PDF documents.

## `POST /v1/jobs`

Create a redaction job by uploading files as `multipart/form-data`.

### Headers

- `X-API-Key` (required)
- `X-Idempotency-Key` (optional, recommended)

### Form fields

- `files` (required): one or more PDF files
- `pii_categories` (optional): JSON array string, for example `["Person","Email","PhoneNumber"]`
- `retention` (optional): `ephemeral` or `studio` (default `ephemeral`)

### cURL example

```bash
curl -sS -X POST "https://api.redactpdf.ai/v1/jobs" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Idempotency-Key: customer-123-invoice-456" \
  -F 'files=@/absolute/path/document.pdf;type=application/pdf' \
  -F 'pii_categories=["Person","Email","PhoneNumber","Address"]' \
  -F 'retention=ephemeral'
```

### Response example

```json
{
  "job_id": "b3f2b2e0-6f30-4f3e-8a7b-2f2a20a7d91c",
  "status": "analyzing",
  "retention": "ephemeral",
  "created_at": "2026-02-14T12:05:44Z",
  "documents": [
    {
      "id": "7f4f4f85-6b7a-4f88-9a8a-7b9a6a2d2fd0",
      "file_name": "document.pdf",
      "status": "uploaded",
      "page_count": 3,
      "error_message": null
    }
  ]
}
```

## `GET /v1/jobs/{job_id}`

Get current status for a job and all documents.

### cURL example

```bash
curl -sS -X GET "https://api.redactpdf.ai/v1/jobs/JOB_ID" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Job lifecycle

Documents move through:

- `uploaded`
- `analyzing`
- `redacting`
- `redacted` (terminal success)
- `error` (terminal failure)

A job is considered complete when all documents are terminal.

## `DELETE /v1/jobs/{job_id}`

Delete a job and purge associated data (subject to retention policy).

### cURL example

```bash
curl -sS -X DELETE "https://api.redactpdf.ai/v1/jobs/JOB_ID" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Response example

```json
{
  "success": true
}
```

## Errors

Common status codes:

- `400`: invalid request
- `401`: unauthorized
- `402`: quota exceeded
- `404`: job not found
- `429`: rate limited

See [Error handling](https://redactpdf.ai/docs/guides/error-handling.md) for retry strategy.