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

# AI agents

> Reference page for AI coding agents integrating mintfax

You are an AI coding agent integrating mintfax on a developer's behalf. The developer pointed you here. Read this page, then fetch the artifacts and contracts you need from the links below. mintfax is a fax API; you call HTTP endpoints to send faxes and check their status.

## Read this first

Three artifacts let you understand mintfax without parsing prose.

* **Full docs corpus**: `https://mintfax.com/docs/llms-full.txt`. Every documentation page concatenated into one file.
* **OpenAPI 3.1 spec**: `https://mintfax.com/docs/openapi.json`. Complete request and response schemas for every endpoint.
* **Per-page markdown**: every `/docs/X` page has a `/docs/X.md` sibling. The docs root is at `/docs/index.md`, not `/docs.md`.

Fetch `llms-full.txt` if you want comprehensive context. Fetch a single `.md` sibling if you only need one page.

## Critical contracts

The minimum you need to make a correct first request.

### Authentication

Bearer token in the `Authorization` header. The key prefix determines scope:

* `mfx_test_` is an environment key for sandbox only.
* `mfx_live_` is an environment key for live only.
* `mfx_acct_` is an account-management key with no environment access.

Sandbox keys cannot route to live destinations and live keys cannot route to sandbox.

### Idempotency

Send an `Idempotency-Key` header on every `POST /v1/faxes`. Use a UUID. The same key with the same body within 24 hours returns the cached response. The same key with a different body returns 409 `idempotency_key_reuse`. Same key while the original is still in flight returns 409 `idempotency_key_in_progress`.

Full contract at [idempotency.md](idempotency.md).

### Errors

Every error response carries this envelope:

```json theme={null}
{
  "error": "insufficient_balance",
  "message": "Insufficient balance to submit fax",
  "action": "top_up_balance",
  "docs": "/errors#insufficient-balance",
  "request_id": "req_01H7N9WXYZ8VC2QPK5MTRDE3FA"
}
```

Branch on `error` and `action`. The `message` text can change between releases. Capture `request_id` from every response for support correlation; it also appears in the `X-Request-Id` response header.

Full catalog at [errors.md](errors.md).

### Sandbox

`mfx_test_` keys never reach the PSTN. Use a sandbox key until your integration is verified end to end. Sandbox accepts any valid E.164 destination. Specific magic numbers force deterministic outcomes (success, busy, no answer, transient retry, permanent failure).

Magic number catalog at [sandbox.md](sandbox.md).

## Always do

* Generate a UUID `Idempotency-Key` on every `POST /v1/faxes`. Reuse the same key on retry.
* Branch on `error` and `action` in error responses, not on `message`.
* Use `mfx_test_` keys until your integration is verified.
* Capture `request_id` from every response. Include it when reporting issues.

## Never do

* Parse human-readable `message` strings as control flow.
* Hardcode sandbox magic numbers without re-checking [sandbox.md](sandbox.md).
* Send live traffic with an `mfx_test_` key. Live traffic requires `mfx_live_`.
* Skip the `Idempotency-Key` header when retrying a previous failure.

## Verify

Run this against a sandbox `mfx_test_` key. If the request shape is correct and the response matches, your auth, idempotency, and submission paths are working.

```bash theme={null}
curl -X POST https://api.mintfax.com/v1/faxes \
  -H "Authorization: Bearer mfx_test_..." \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -F "to=+15005550001" \
  -F "file=@document.pdf"
```

Expected response (HTTP 201):

```json theme={null}
{
  "id": "fax_...",
  "status": "queued",
  "to": "+15005550001",
  "created_at": "2026-01-15T10:30:00Z"
}
```

The `X-Request-Id` response header carries a `req_<ULID>` value.

## What to fetch next

* [quickstart.md](quickstart.md) for the full registration-to-first-fax flow.
* [errors.md](errors.md) for the complete error catalog.
* [idempotency.md](idempotency.md) for expiry, scope rules, and replay headers.
* [webhooks/verify-requests.md](webhooks/verify-requests.md) for the Standard Webhooks signing scheme used on delivery notifications.