# Full API reference

> Static HTML from the OpenAPI snapshot of 2026-10-31. Every operation, parameter, request body, response and schema. No JavaScript needed.

Page: https://faxforagents.com/docs/api/reference/
Last changed: 2026-10-28

Updated Oct 28, 2026

Every operation of the Fax for Agents API as static HTML. 147 operations and 149 schemas from the OpenAPI document version 1.4.0, snapshot of 2026-10-31. The base URL is `https://api.faxforagents.com/v1`. The same document is at [/openapi.json](https://faxforagents.com/openapi.json).

## agents

- `GET /v1/agents` List agent identities
- `POST /v1/agents` Register an agent identity
- `GET /v1/agents/{agent_id}` Read an agent with its keys and budgets
- `PATCH /v1/agents/{agent_id}` Change an agent; disabling revokes its keys
- `GET /v1/agents/{agent_id}/activity` The agent's audit trail
- `POST /v1/agents/{agent_id}/keys` Mint a key for the agent (bounded scopes, secret shown once)

### GET `/v1/agents`

List agent identities

#### Responses

GET /v1/agents responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/agents response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Agent | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/agents \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/agents`

Register an agent identity

#### Request body application/json, required

POST /v1/agents request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contact_email` | string or null | no | Where decided approvals are mailed. |
| `name` | string | yes |  |
| `policy_ids` | array of string | no |  |
| `purpose` | string or null | no | Shown to humans, never evaluated. |

#### Responses

POST /v1/agents responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/agents response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `budget_id` | string or null | yes |  |
| `budgets` | array of object | yes |  |
| `contact_email` | string or null | yes |  |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `disabled_at` | string or null | yes |  |
| `enabled` | boolean | yes |  |
| `id` | string | yes |  |
| `keys` | array of object ApiKey | yes |  |
| `name` | string | yes |  |
| `policy_ids` | array of string | yes |  |
| `project_id` | string or null | yes |  |
| `purpose` | string or null | yes |  |
| `status` | string | yes |  |
| `updated_at` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/agents \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/agents/{agent_id}`

Read an agent with its keys and budgets

#### Parameters

GET /v1/agents/{agent_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `agent_id` | path | string | yes |  |

#### Responses

GET /v1/agents/{agent_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/agents/{agent_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `budget_id` | string or null | yes |  |
| `budgets` | array of object | yes |  |
| `contact_email` | string or null | yes |  |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `disabled_at` | string or null | yes |  |
| `enabled` | boolean | yes |  |
| `id` | string | yes |  |
| `keys` | array of object ApiKey | yes |  |
| `name` | string | yes |  |
| `policy_ids` | array of string | yes |  |
| `project_id` | string or null | yes |  |
| `purpose` | string or null | yes |  |
| `status` | string | yes |  |
| `updated_at` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/agents/AGENT_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### PATCH `/v1/agents/{agent_id}`

Change an agent; disabling revokes its keys

#### Parameters

PATCH /v1/agents/{agent_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `agent_id` | path | string | yes |  |

#### Request body application/json, required

PATCH /v1/agents/{agent_id} request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contact_email` | string or null | no |  |
| `enabled` | boolean or null | no | false revokes every key of the agent. |
| `name` | string or null | no |  |
| `policy_ids` | array of string or null | no |  |
| `purpose` | string or null | no |  |

#### Responses

PATCH /v1/agents/{agent_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

PATCH /v1/agents/{agent_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `budget_id` | string or null | yes |  |
| `budgets` | array of object | yes |  |
| `contact_email` | string or null | yes |  |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `disabled_at` | string or null | yes |  |
| `enabled` | boolean | yes |  |
| `id` | string | yes |  |
| `keys` | array of object ApiKey | yes |  |
| `name` | string | yes |  |
| `policy_ids` | array of string | yes |  |
| `project_id` | string or null | yes |  |
| `purpose` | string or null | yes |  |
| `status` | string | yes |  |
| `updated_at` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/agents/AGENT_ID \ -X PATCH \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/agents/{agent_id}/activity`

The agent's audit trail

#### Parameters

GET /v1/agents/{agent_id}/activity parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `agent_id` | path | string | yes |  |
| `cursor` | query | string or null | no |  |
| `limit` | query | integer | no | Default `50` . |

#### Responses

GET /v1/agents/{agent_id}/activity responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/agents/{agent_id}/activity response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object AgentActivity | yes |  |
| `next_cursor` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/agents/AGENT_ID/activity \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/agents/{agent_id}/keys`

Mint a key for the agent (bounded scopes, secret shown once)

#### Parameters

POST /v1/agents/{agent_id}/keys parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `agent_id` | path | string | yes |  |

#### Request body application/json, required

POST /v1/agents/{agent_id}/keys request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `environment` | string (live, test) | no |  |
| `expires_in_days` | integer or null | no |  |
| `label` | string | no |  |
| `scopes` | array of string or null | no | Omit for the default agent set. Never approval:decide, key:admin, policy:admin, agent:admin. |

#### Responses

POST /v1/agents/{agent_id}/keys responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/agents/{agent_id}/keys response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_id` | string or null | yes |  |
| `created_at` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `expires_at` | string or null | yes |  |
| `id` | string | yes |  |
| `label` | string | yes |  |
| `last_used_at` | string or null | yes |  |
| `prefix` | string | yes |  |
| `project_id` | string or null | yes |  |
| `revoked_at` | string or null | yes |  |
| `rotated_from_id` | string or null | yes |  |
| `scopes` | array of string | yes |  |
| `secret` | string | yes | Shown once. Store it now; it cannot be read back. |

#### Example

```
`curl https://api.faxforagents.com/v1/agents/AGENT_ID/keys \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

## identity

- `GET /v1/api-keys` List API keys (metadata only)
- `POST /v1/api-keys` Create an API key (the secret is shown once)
- `DELETE /v1/api-keys/{key_id}` Revoke a key
- `POST /v1/api-keys/{key_id}/rotate` Rotate a key: a new secret, the old one works for 24 more hours
- `GET /v1/me` Who am I

### GET `/v1/api-keys`

List API keys (metadata only)

#### Responses

GET /v1/api-keys responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/api-keys response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object ApiKey | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/api-keys \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/api-keys`

Create an API key (the secret is shown once)

#### Request body application/json, required

POST /v1/api-keys request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `environment` | string (live, test) | no |  |
| `expires_in_days` | integer or null | no |  |
| `label` | string | yes |  |
| `scopes` | array of string or null | no | Omit for the default agent set; '*' for all. |

#### Responses

POST /v1/api-keys responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/api-keys response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_id` | string or null | yes |  |
| `created_at` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `expires_at` | string or null | yes |  |
| `id` | string | yes |  |
| `label` | string | yes |  |
| `last_used_at` | string or null | yes |  |
| `prefix` | string | yes |  |
| `project_id` | string or null | yes |  |
| `revoked_at` | string or null | yes |  |
| `rotated_from_id` | string or null | yes |  |
| `scopes` | array of string | yes |  |
| `secret` | string | yes | Shown once. Store it now; it cannot be read back. |

#### Example

```
`curl https://api.faxforagents.com/v1/api-keys \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### DELETE `/v1/api-keys/{key_id}`

Revoke a key

#### Parameters

DELETE /v1/api-keys/{key_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `key_id` | path | string | yes |  |

#### Responses

DELETE /v1/api-keys/{key_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

DELETE /v1/api-keys/{key_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | boolean | no |  |
| `id` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/api-keys/KEY_ID \ -X DELETE \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/api-keys/{key_id}/rotate`

Rotate a key: a new secret, the old one works for 24 more hours

#### Parameters

POST /v1/api-keys/{key_id}/rotate parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `key_id` | path | string | yes |  |

#### Responses

POST /v1/api-keys/{key_id}/rotate responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/api-keys/{key_id}/rotate response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_id` | string or null | yes |  |
| `created_at` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `expires_at` | string or null | yes |  |
| `id` | string | yes |  |
| `label` | string | yes |  |
| `last_used_at` | string or null | yes |  |
| `prefix` | string | yes |  |
| `project_id` | string or null | yes |  |
| `revoked_at` | string or null | yes |  |
| `rotated_from_id` | string or null | yes |  |
| `scopes` | array of string | yes |  |
| `secret` | string | yes | Shown once. Store it now; it cannot be read back. |

#### Example

```
`curl https://api.faxforagents.com/v1/api-keys/KEY_ID/rotate \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/me`

Who am I

#### Responses

GET /v1/me responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/me response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actor` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `key_id` | string | yes |  |
| `key_prefix` | string | yes |  |
| `org_id` | string | yes |  |
| `project_id` | string | yes |  |
| `scopes` | array of string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/me \ -H "Authorization: Bearer ffa_test_..."`
```

## approvals

- `GET /v1/approval-requests` Approval requests, pending first
- `POST /v1/approval-requests` Ask a human to approve a quoted send, or ask for help (grants nothing)
- `GET /v1/approval-requests/{approval_id}` Read one request
- `POST /v1/approval-requests/{approval_id}/approve` Approve the bound quote (a human with approval:decide, never the requester)
- `POST /v1/approval-requests/{approval_id}/reject` Reject with a reason
- `POST /v1/approvals/{approval_id}/revoke` Revoke an approval nobody has used yet

### GET `/v1/approval-requests`

Approval requests, pending first

#### Parameters

GET /v1/approval-requests parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `status` | query | string or null | no |  |
| `cursor` | query | string or null | no |  |
| `limit` | query | integer | no | Default `50` . |

#### Responses

GET /v1/approval-requests responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/approval-requests response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object ApprovalRequest | yes |  |
| `next_cursor` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/approval-requests \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/approval-requests`

Ask a human to approve a quoted send, or ask for help (grants nothing)

#### Request body application/json, required

POST /v1/approval-requests request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fax_job_id` | string or null | no |  |
| `kind` | string (send, help) | no |  |
| `message` | string or null | no | What the person should know (kind help). Shown as data. |
| `quote_id` | string or null | no | The quote to bind (kind send). |

#### Responses

POST /v1/approval-requests responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/approval-requests response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `bound` | object | yes |  |
| `consumed_by_job_id` | string or null | yes |  |
| `created_at` | string | yes |  |
| `decided_at` | string or null | yes |  |
| `decided_by` | string or null | yes |  |
| `expires_at` | string or null | yes |  |
| `id` | string | yes |  |
| `kind` | string (send, help) | yes |  |
| `message` | string or null | yes |  |
| `notified` | boolean or null | no | On creation: whether the organization was mailed. false when the request repeats a pending one or the organization's daily cap of request mails is reached; the request is still shown in the dashboard. |
| `quote_id` | string or null | yes |  |
| `reason` | string or null | yes |  |
| `requested_by` | string | yes |  |
| `status` | string (pending, approved, rejected, revoked, expired) | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/approval-requests \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/approval-requests/{approval_id}`

Read one request

#### Parameters

GET /v1/approval-requests/{approval_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `approval_id` | path | string | yes |  |

#### Responses

GET /v1/approval-requests/{approval_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/approval-requests/{approval_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `bound` | object | yes |  |
| `consumed_by_job_id` | string or null | yes |  |
| `created_at` | string | yes |  |
| `decided_at` | string or null | yes |  |
| `decided_by` | string or null | yes |  |
| `expires_at` | string or null | yes |  |
| `id` | string | yes |  |
| `kind` | string (send, help) | yes |  |
| `message` | string or null | yes |  |
| `notified` | boolean or null | no | On creation: whether the organization was mailed. false when the request repeats a pending one or the organization's daily cap of request mails is reached; the request is still shown in the dashboard. |
| `quote_id` | string or null | yes |  |
| `reason` | string or null | yes |  |
| `requested_by` | string | yes |  |
| `status` | string (pending, approved, rejected, revoked, expired) | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/approval-requests/APPROVAL_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/approval-requests/{approval_id}/approve`

Approve the bound quote (a human with approval:decide, never the requester)

#### Parameters

POST /v1/approval-requests/{approval_id}/approve parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `approval_id` | path | string | yes |  |

#### Request body application/json, required

POST /v1/approval-requests/{approval_id}/approve request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string or null | no |  |

#### Responses

POST /v1/approval-requests/{approval_id}/approve responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/approval-requests/{approval_id}/approve response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `bound` | object | yes |  |
| `consumed_by_job_id` | string or null | yes |  |
| `created_at` | string | yes |  |
| `decided_at` | string or null | yes |  |
| `decided_by` | string or null | yes |  |
| `expires_at` | string or null | yes |  |
| `id` | string | yes |  |
| `kind` | string (send, help) | yes |  |
| `message` | string or null | yes |  |
| `notified` | boolean or null | no | On creation: whether the organization was mailed. false when the request repeats a pending one or the organization's daily cap of request mails is reached; the request is still shown in the dashboard. |
| `quote_id` | string or null | yes |  |
| `reason` | string or null | yes |  |
| `requested_by` | string | yes |  |
| `status` | string (pending, approved, rejected, revoked, expired) | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/approval-requests/APPROVAL_ID/approve \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/approval-requests/{approval_id}/reject`

Reject with a reason

#### Parameters

POST /v1/approval-requests/{approval_id}/reject parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `approval_id` | path | string | yes |  |

#### Request body application/json, required

POST /v1/approval-requests/{approval_id}/reject request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string or null | no |  |

#### Responses

POST /v1/approval-requests/{approval_id}/reject responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/approval-requests/{approval_id}/reject response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `bound` | object | yes |  |
| `consumed_by_job_id` | string or null | yes |  |
| `created_at` | string | yes |  |
| `decided_at` | string or null | yes |  |
| `decided_by` | string or null | yes |  |
| `expires_at` | string or null | yes |  |
| `id` | string | yes |  |
| `kind` | string (send, help) | yes |  |
| `message` | string or null | yes |  |
| `notified` | boolean or null | no | On creation: whether the organization was mailed. false when the request repeats a pending one or the organization's daily cap of request mails is reached; the request is still shown in the dashboard. |
| `quote_id` | string or null | yes |  |
| `reason` | string or null | yes |  |
| `requested_by` | string | yes |  |
| `status` | string (pending, approved, rejected, revoked, expired) | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/approval-requests/APPROVAL_ID/reject \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/approvals/{approval_id}/revoke`

Revoke an approval nobody has used yet

#### Parameters

POST /v1/approvals/{approval_id}/revoke parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `approval_id` | path | string | yes |  |

#### Request body application/json, required

POST /v1/approvals/{approval_id}/revoke request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string or null | no |  |

#### Responses

POST /v1/approvals/{approval_id}/revoke responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/approvals/{approval_id}/revoke response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `bound` | object | yes |  |
| `consumed_by_job_id` | string or null | yes |  |
| `created_at` | string | yes |  |
| `decided_at` | string or null | yes |  |
| `decided_by` | string or null | yes |  |
| `expires_at` | string or null | yes |  |
| `id` | string | yes |  |
| `kind` | string (send, help) | yes |  |
| `message` | string or null | yes |  |
| `notified` | boolean or null | no | On creation: whether the organization was mailed. false when the request repeats a pending one or the organization's daily cap of request mails is reached; the request is still shown in the dashboard. |
| `quote_id` | string or null | yes |  |
| `reason` | string or null | yes |  |
| `requested_by` | string | yes |  |
| `status` | string (pending, approved, rejected, revoked, expired) | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/approvals/APPROVAL_ID/revoke \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

## auth

- `POST /v1/auth/invitations/{token}/accept` Join the organization an invitation link names (the signed-in email must match)
- `POST /v1/auth/logout` End this session
- `POST /v1/auth/magic-links` Send a sign-in link to an email address (always 202)
- `GET /v1/auth/magic-links/{token}` Open a sign-in link: sets the session cookie and redirects to the app
- `GET /v1/auth/me` The signed-in person, their organizations and the CSRF token
- `GET /v1/auth/oauth/{provider}/callback` Finish GitHub or Google sign-in (the app forwards its /auth/{provider}/callback here)
- `GET /v1/auth/oauth/{provider}/start` Begin GitHub or Google sign-in (redirects to the provider)
- `GET /v1/auth/passkeys` Your passkeys
- `POST /v1/auth/passkeys/login/options` Options for navigator.credentials.get() (discoverable, no email needed)
- `POST /v1/auth/passkeys/login/verify` Sign in with a passkey assertion
- `POST /v1/auth/passkeys/register/options` Options for navigator.credentials.create() (fresh session required)
- `POST /v1/auth/passkeys/register/verify` Store a new passkey after the browser created it
- `DELETE /v1/auth/passkeys/{passkey_id}` Remove one of your passkeys
- `GET /v1/auth/providers` Which sign-in methods are available
- `POST /v1/auth/reauth` Prove it is you again (passkey now, or a fresh link by mail) before a sensitive action
- `DELETE /v1/auth/sessions` Sign out everywhere else
- `GET /v1/auth/sessions` Your live sessions
- `DELETE /v1/auth/sessions/{session_id}` Revoke one of your sessions
- `POST /v1/auth/switch-organization` Look at another organization you belong to

### POST `/v1/auth/invitations/{token}/accept`

Join the organization an invitation link names (the signed-in email must match)

#### Parameters

POST /v1/auth/invitations/{token}/accept parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `token` | path | string | yes |  |

#### Responses

POST /v1/auth/invitations/{token}/accept responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/auth/invitations/{token}/accept response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `organization` | object OrganizationSummary | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/invitations/TOKEN/accept \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/auth/logout`

End this session

#### Responses

POST /v1/auth/logout responses

| Status | Meaning |
| --- | --- |
| `204` | Successful Response |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/logout \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/auth/magic-links`

Send a sign-in link to an email address (always 202)

#### Request body application/json, required

POST /v1/auth/magic-links request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `next` | string or null | no | An in-app path to open after sign-in. |

#### Responses

POST /v1/auth/magic-links responses

| Status | Meaning |
| --- | --- |
| `202` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/auth/magic-links response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | string | yes |  |
| `sent` | boolean | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/magic-links \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/auth/magic-links/{token}`

Open a sign-in link: sets the session cookie and redirects to the app

#### Parameters

GET /v1/auth/magic-links/{token} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `token` | path | string | yes |  |

#### Responses

GET /v1/auth/magic-links/{token} responses

| Status | Meaning |
| --- | --- |
| `303` | Redirect to the app, signed in or with an error code in the query. |
| `422` | Validation Error |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/magic-links/TOKEN \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/auth/me`

The signed-in person, their organizations and the CSRF token

#### Responses

GET /v1/auth/me responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/auth/me response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `csrf_token` | string | yes |  |
| `organization` | object OrganizationSummary or null | yes |  |
| `organizations` | array of object OrganizationSummary | yes |  |
| `passkeys` | integer | yes |  |
| `providers` | object Providers | yes |  |
| `session` | object SessionInfo | yes |  |
| `user` | object UserOut | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/me \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/auth/oauth/{provider}/callback`

Finish GitHub or Google sign-in (the app forwards its /auth/{provider}/callback here)

#### Parameters

GET /v1/auth/oauth/{provider}/callback parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `provider` | path | string | yes |  |
| `code` | query | string | no | Default `""` . |
| `state` | query | string | no | Default `""` . |
| `error` | query | string or null | no |  |

#### Responses

GET /v1/auth/oauth/{provider}/callback responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/auth/oauth/{provider}/callback response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `csrf_token` | string | yes |  |
| `organization` | object OrganizationSummary or null | yes |  |
| `organizations` | array of object OrganizationSummary | yes |  |
| `passkeys` | integer | yes |  |
| `providers` | object Providers | yes |  |
| `session` | object SessionInfo | yes |  |
| `user` | object UserOut | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/oauth/PROVIDER/callback \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/auth/oauth/{provider}/start`

Begin GitHub or Google sign-in (redirects to the provider)

#### Parameters

GET /v1/auth/oauth/{provider}/start parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `provider` | path | string | yes |  |
| `next` | query | string or null | no |  |

#### Responses

GET /v1/auth/oauth/{provider}/start responses

| Status | Meaning |
| --- | --- |
| `303` | Successful Response |
| `422` | Validation Error |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/oauth/PROVIDER/start \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/auth/passkeys`

Your passkeys

#### Responses

GET /v1/auth/passkeys responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/auth/passkeys response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Passkey | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/passkeys \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/auth/passkeys/login/options`

Options for navigator.credentials.get() (discoverable, no email needed)

#### Responses

POST /v1/auth/passkeys/login/options responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/passkeys/login/options \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/auth/passkeys/login/verify`

Sign in with a passkey assertion

#### Request body application/json, required

POST /v1/auth/passkeys/login/verify request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `credential` | object | yes |  |

#### Responses

POST /v1/auth/passkeys/login/verify responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/auth/passkeys/login/verify response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `csrf_token` | string | yes |  |
| `organization` | object OrganizationSummary or null | yes |  |
| `organizations` | array of object OrganizationSummary | yes |  |
| `passkeys` | integer | yes |  |
| `providers` | object Providers | yes |  |
| `session` | object SessionInfo | yes |  |
| `user` | object UserOut | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/passkeys/login/verify \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/auth/passkeys/register/options`

Options for navigator.credentials.create() (fresh session required)

#### Responses

POST /v1/auth/passkeys/register/options responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/passkeys/register/options \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/auth/passkeys/register/verify`

Store a new passkey after the browser created it

#### Request body application/json, required

POST /v1/auth/passkeys/register/verify request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `credential` | object | yes |  |
| `label` | string or null | no |  |

#### Responses

POST /v1/auth/passkeys/register/verify responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/auth/passkeys/register/verify response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `aaguid` | string or null | yes |  |
| `backup_eligible` | boolean | yes |  |
| `created_at` | string | yes |  |
| `id` | string | yes |  |
| `label` | string or null | yes |  |
| `last_used_at` | string or null | yes |  |
| `transports` | array of string or null | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/passkeys/register/verify \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### DELETE `/v1/auth/passkeys/{passkey_id}`

Remove one of your passkeys

#### Parameters

DELETE /v1/auth/passkeys/{passkey_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `passkey_id` | path | string | yes |  |

#### Responses

DELETE /v1/auth/passkeys/{passkey_id} responses

| Status | Meaning |
| --- | --- |
| `204` | Successful Response |
| `422` | Validation Error |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/passkeys/PASSKEY_ID \ -X DELETE \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/auth/providers`

Which sign-in methods are available

#### Responses

GET /v1/auth/providers responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/auth/providers response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `github` | boolean | yes |  |
| `google` | boolean | yes |  |
| `magic_link` | boolean | no |  |
| `passkeys` | boolean | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/providers \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/auth/reauth`

Prove it is you again (passkey now, or a fresh link by mail) before a sensitive action

#### Request body application/json, required

POST /v1/auth/reauth request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `credential` | object or null | no |  |
| `method` | string (passkey, magic_link) | yes |  |

#### Responses

POST /v1/auth/reauth responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `202` | A sign-in link was sent; opening it in this browser refreshes the session. |
| `422` | Validation Error |

#### Response fields

POST /v1/auth/reauth response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `csrf_token` | string | yes |  |
| `organization` | object OrganizationSummary or null | yes |  |
| `organizations` | array of object OrganizationSummary | yes |  |
| `passkeys` | integer | yes |  |
| `providers` | object Providers | yes |  |
| `session` | object SessionInfo | yes |  |
| `user` | object UserOut | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/reauth \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### DELETE `/v1/auth/sessions`

Sign out everywhere else

#### Responses

DELETE /v1/auth/sessions responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

DELETE /v1/auth/sessions response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `revoked` | integer | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/sessions \ -X DELETE \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/auth/sessions`

Your live sessions

#### Responses

GET /v1/auth/sessions responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/auth/sessions response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object SessionOut | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/sessions \ -H "Authorization: Bearer ffa_test_..."`
```

### DELETE `/v1/auth/sessions/{session_id}`

Revoke one of your sessions

#### Parameters

DELETE /v1/auth/sessions/{session_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `session_id` | path | string | yes |  |

#### Responses

DELETE /v1/auth/sessions/{session_id} responses

| Status | Meaning |
| --- | --- |
| `204` | Successful Response |
| `422` | Validation Error |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/sessions/SESSION_ID \ -X DELETE \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/auth/switch-organization`

Look at another organization you belong to

#### Request body application/json, required

POST /v1/auth/switch-organization request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `org_id` | string | yes |  |

#### Responses

POST /v1/auth/switch-organization responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/auth/switch-organization response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `csrf_token` | string | yes |  |
| `organization` | object OrganizationSummary or null | yes |  |
| `organizations` | array of object OrganizationSummary | yes |  |
| `passkeys` | integer | yes |  |
| `providers` | object Providers | yes |  |
| `session` | object SessionInfo | yes |  |
| `user` | object UserOut | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/auth/switch-organization \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

## billing

- `GET /v1/auto-topups` Auto top-up settings
- `POST /v1/auto-topups` Opt in to auto top-up (threshold, amount, daily cap); the card is saved at the first payment
- `DELETE /v1/auto-topups/{auto_topup_id}` Turn auto top-up off
- `GET /v1/balance` Available and held balance
- `POST /v1/billing-portal-sessions` Open the Stripe customer portal (cards, invoices, the subscription)
- `GET /v1/billing-settings` Billing settings of the organization
- `PATCH /v1/billing-settings` Change the billing email or the low-balance threshold
- `GET /v1/budgets` Spending caps of this environment
- `POST /v1/budgets` Create a daily or monthly cap for the organization, a project or an agent
- `PATCH /v1/budgets/{budget_id}` Change a cap's limit or status
- `GET /v1/invoices` Stripe invoices and receipts (hosted links)
- `GET /v1/invoices/{invoice_id}` One Stripe invoice
- `GET /v1/ledger` Wallet transactions, newest first
- `GET /v1/subscriptions` Subscriptions and the workspace entitlement
- `POST /v1/subscriptions/checkout` Open a hosted Checkout for the Agent workspace subscription
- `GET /v1/topup-sessions` Top-up sessions, newest first
- `POST /v1/topup-sessions` Open a hosted Checkout to fund the live wallet (10 to 1000 USD)
- `GET /v1/topup-sessions/{topup_session_id}` Read a top-up session
- `GET /v1/usage` Usage rollups by day, direction, destination and project
- `POST /v1/usage-exports` Export usage as CSV behind a signed download
- `GET /v1/usage-exports/{export_id}` Read a usage export (fresh link)
- `GET /v1/usage-exports/{export_id}/content` The CSV behind a signed URL (no API key)

### GET `/v1/auto-topups`

Auto top-up settings

#### Responses

GET /v1/auto-topups responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/auto-topups response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object AutoTopup | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/auto-topups \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/auto-topups`

Opt in to auto top-up (threshold, amount, daily cap); the card is saved at the first payment

#### Request body application/json, required

POST /v1/auto-topups request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes | Whole dollars, 10 to 1000 USD. |
| `daily_cap_micro` | integer | yes | Never more than this per UTC day. |
| `threshold_micro` | integer | yes | Top up when the available balance drops below this. |

#### Responses

POST /v1/auto-topups responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/auto-topups response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `created_at` | string | yes |  |
| `daily_cap_micro` | integer | yes |  |
| `disabled_at` | string or null | yes |  |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `last_attempt_at` | string or null | yes |  |
| `payment_method_saved` | boolean | yes |  |
| `setup_session_id` | string or null | yes |  |
| `setup_url` | string or null | no | Where to save the card while status is pending_setup. |
| `status` | string (pending_setup, active, disabled) | yes |  |
| `threshold_micro` | integer | yes |  |
| `updated_at` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/auto-topups \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### DELETE `/v1/auto-topups/{auto_topup_id}`

Turn auto top-up off

#### Parameters

DELETE /v1/auto-topups/{auto_topup_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `auto_topup_id` | path | string | yes |  |

#### Responses

DELETE /v1/auto-topups/{auto_topup_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

DELETE /v1/auto-topups/{auto_topup_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | boolean | no |  |
| `id` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/auto-topups/AUTO_TOPUP_ID \ -X DELETE \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/balance`

Available and held balance

#### Responses

GET /v1/balance responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/balance response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `available_micro` | integer | yes |  |
| `currency` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `held_micro` | integer | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/balance \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/billing-portal-sessions`

Open the Stripe customer portal (cards, invoices, the subscription)

#### Responses

POST /v1/billing-portal-sessions responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |

#### Response fields

POST /v1/billing-portal-sessions response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expires_at` | string | yes |  |
| `url` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/billing-portal-sessions \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/billing-settings`

Billing settings of the organization

#### Responses

GET /v1/billing-settings responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/billing-settings response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `billing_email` | string or null | yes |  |
| `disputed` | boolean | yes |  |
| `low_balance_active` | boolean | yes |  |
| `low_balance_threshold_micro` | integer | yes |  |
| `org_id` | string | yes |  |
| `stripe_customer` | boolean | yes |  |
| `workspace` | boolean | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/billing-settings \ -H "Authorization: Bearer ffa_test_..."`
```

### PATCH `/v1/billing-settings`

Change the billing email or the low-balance threshold

#### Request body application/json, required

PATCH /v1/billing-settings request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `billing_email` | string or null | no |  |
| `low_balance_threshold_micro` | integer or null | no |  |

#### Responses

PATCH /v1/billing-settings responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

PATCH /v1/billing-settings response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `billing_email` | string or null | yes |  |
| `disputed` | boolean | yes |  |
| `low_balance_active` | boolean | yes |  |
| `low_balance_threshold_micro` | integer | yes |  |
| `org_id` | string | yes |  |
| `stripe_customer` | boolean | yes |  |
| `workspace` | boolean | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/billing-settings \ -X PATCH \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/budgets`

Spending caps of this environment

#### Responses

GET /v1/budgets responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/budgets response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Budget | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/budgets \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/budgets`

Create a daily or monthly cap for the organization, a project or an agent

#### Request body application/json, required

POST /v1/budgets request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_id` | string or null | no |  |
| `limit_micro` | integer | yes |  |
| `period` | string (daily, monthly) | yes |  |
| `project_id` | string or null | no |  |
| `scope` | string (organization, project, agent) | no |  |

#### Responses

POST /v1/budgets responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/budgets response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_id` | string or null | yes |  |
| `created_at` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `limit_micro` | integer | yes |  |
| `period` | string (daily, monthly) | yes |  |
| `project_id` | string or null | yes |  |
| `remaining_micro` | integer | yes |  |
| `resets_at` | string | yes |  |
| `scope` | string (organization, project, agent) | yes |  |
| `spent_micro` | integer | yes |  |
| `status` | string (active, disabled) | yes |  |
| `updated_at` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/budgets \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### PATCH `/v1/budgets/{budget_id}`

Change a cap's limit or status

#### Parameters

PATCH /v1/budgets/{budget_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `budget_id` | path | string | yes |  |

#### Request body application/json, required

PATCH /v1/budgets/{budget_id} request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit_micro` | integer or null | no |  |
| `status` | string (active, disabled) or null | no |  |

#### Responses

PATCH /v1/budgets/{budget_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

PATCH /v1/budgets/{budget_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_id` | string or null | yes |  |
| `created_at` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `limit_micro` | integer | yes |  |
| `period` | string (daily, monthly) | yes |  |
| `project_id` | string or null | yes |  |
| `remaining_micro` | integer | yes |  |
| `resets_at` | string | yes |  |
| `scope` | string (organization, project, agent) | yes |  |
| `spent_micro` | integer | yes |  |
| `status` | string (active, disabled) | yes |  |
| `updated_at` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/budgets/BUDGET_ID \ -X PATCH \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/invoices`

Stripe invoices and receipts (hosted links)

#### Parameters

GET /v1/invoices parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `cursor` | query | string or null | no |  |
| `limit` | query | integer | no | Default `20` . |

#### Responses

GET /v1/invoices responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/invoices response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Invoice | yes |  |
| `next_cursor` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/invoices \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/invoices/{invoice_id}`

One Stripe invoice

#### Parameters

GET /v1/invoices/{invoice_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `invoice_id` | path | string | yes |  |

#### Responses

GET /v1/invoices/{invoice_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/invoices/{invoice_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_due_micro` | integer | yes |  |
| `amount_paid_micro` | integer | yes |  |
| `created_at` | string or null | yes |  |
| `currency` | string | yes |  |
| `hosted_invoice_url` | string or null | yes |  |
| `id` | string | yes |  |
| `invoice_pdf` | string or null | yes |  |
| `number` | string or null | yes |  |
| `status` | string or null | yes |  |
| `subscription_id` | string or null | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/invoices/INVOICE_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/ledger`

Wallet transactions, newest first

#### Parameters

GET /v1/ledger parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `cursor` | query | string or null | no |  |
| `limit` | query | integer | no | Default `50` . |

#### Responses

GET /v1/ledger responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/ledger response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object LedgerEntry | yes |  |
| `next_cursor` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/ledger \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/subscriptions`

Subscriptions and the workspace entitlement

#### Responses

GET /v1/subscriptions responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/subscriptions response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Subscription | yes |  |
| `next_cursor` | string or null | no |  |
| `workspace` | boolean | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/subscriptions \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/subscriptions/checkout`

Open a hosted Checkout for the Agent workspace subscription

#### Responses

POST /v1/subscriptions/checkout responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |

#### Response fields

POST /v1/subscriptions/checkout response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product` | string | yes |  |
| `stripe_session_id` | string | yes |  |
| `url` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/subscriptions/checkout \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/topup-sessions`

Top-up sessions, newest first

#### Parameters

GET /v1/topup-sessions parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `cursor` | query | string or null | no |  |
| `limit` | query | integer | no | Default `50` . |

#### Responses

GET /v1/topup-sessions responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/topup-sessions response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object TopupSession | yes |  |
| `next_cursor` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/topup-sessions \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/topup-sessions`

Open a hosted Checkout to fund the live wallet (10 to 1000 USD)

#### Request body application/json, required

POST /v1/topup-sessions request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_usd` | integer | yes | Whole US dollars, 10 to 1000 per session. |

#### Responses

POST /v1/topup-sessions responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/topup-sessions response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `auto_topup_id` | string or null | yes |  |
| `completed_at` | string or null | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `error` | string or null | yes |  |
| `expires_at` | string or null | yes |  |
| `id` | string | yes |  |
| `kind` | string (manual, auto, setup) | yes |  |
| `status` | string (open, completed, expired, canceled, failed) | yes |  |
| `stripe_payment_intent_id` | string or null | yes |  |
| `stripe_session_id` | string or null | yes |  |
| `url` | string or null | no | The hosted Checkout page while the session is open. |

#### Example

```
`curl https://api.faxforagents.com/v1/topup-sessions \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/topup-sessions/{topup_session_id}`

Read a top-up session

#### Parameters

GET /v1/topup-sessions/{topup_session_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `topup_session_id` | path | string | yes |  |

#### Responses

GET /v1/topup-sessions/{topup_session_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/topup-sessions/{topup_session_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `auto_topup_id` | string or null | yes |  |
| `completed_at` | string or null | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `error` | string or null | yes |  |
| `expires_at` | string or null | yes |  |
| `id` | string | yes |  |
| `kind` | string (manual, auto, setup) | yes |  |
| `status` | string (open, completed, expired, canceled, failed) | yes |  |
| `stripe_payment_intent_id` | string or null | yes |  |
| `stripe_session_id` | string or null | yes |  |
| `url` | string or null | no | The hosted Checkout page while the session is open. |

#### Example

```
`curl https://api.faxforagents.com/v1/topup-sessions/TOPUP_SESSION_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/usage`

Usage rollups by day, direction, destination and project

#### Parameters

GET /v1/usage parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `from` | query | string or null | no |  |
| `to` | query | string or null | no |  |
| `group_by` | query | string | no | Comma-separated subset. Default `"day,direction,route,project"` . |
| `project_id` | query | string or null | no |  |

#### Responses

GET /v1/usage responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/usage response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `currency` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `from` | string | yes |  |
| `group_by` | array of string | yes |  |
| `items` | array of object UsageItem | yes |  |
| `to` | string | yes |  |
| `totals` | object | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/usage \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/usage-exports`

Export usage as CSV behind a signed download

#### Request body application/json, required

POST /v1/usage-exports request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string or null | no | ISO date; default 30 days ago. |
| `to` | string or null | no | ISO date; default today. |

#### Responses

POST /v1/usage-exports responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/usage-exports response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content_type` | string | yes |  |
| `created_at` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `expires_at` | string | yes |  |
| `id` | string | yes |  |
| `params` | object | yes |  |
| `row_count` | integer | yes |  |
| `status` | string (ready, expired) | yes |  |
| `url` | string or null | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/usage-exports \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/usage-exports/{export_id}`

Read a usage export (fresh link)

#### Parameters

GET /v1/usage-exports/{export_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `export_id` | path | string | yes |  |

#### Responses

GET /v1/usage-exports/{export_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/usage-exports/{export_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content_type` | string | yes |  |
| `created_at` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `expires_at` | string | yes |  |
| `id` | string | yes |  |
| `params` | object | yes |  |
| `row_count` | integer | yes |  |
| `status` | string (ready, expired) | yes |  |
| `url` | string or null | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/usage-exports/EXPORT_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/usage-exports/{export_id}/content`

The CSV behind a signed URL (no API key)

#### Parameters

GET /v1/usage-exports/{export_id}/content parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `export_id` | path | string | yes |  |
| `exp` | query | string or null | no |  |
| `sig` | query | string or null | no |  |

#### Responses

GET /v1/usage-exports/{export_id}/content responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Example

```
`curl https://api.faxforagents.com/v1/usage-exports/EXPORT_ID/content \ -H "Authorization: Bearer ffa_test_..."`
```

## platform

- `GET /v1/capabilities` Limits and features in force
- `GET /v1/service-status` Customer-safe availability

### GET `/v1/capabilities`

Limits and features in force

#### Responses

GET /v1/capabilities responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/capabilities response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `approvals` | boolean | yes |  |
| `environment` | string (live, test) | yes |  |
| `formats` | array of string | yes |  |
| `limits` | object | yes |  |
| `max_pages` | integer | yes |  |
| `max_upload_bytes` | integer | yes |  |
| `numbers` | boolean | yes |  |
| `one_time` | object | yes |  |
| `price_version` | string | yes |  |
| `provider` | string | yes |  |
| `rates` | object | yes |  |
| `receive` | boolean | yes |  |
| `routes` | array of string | yes |  |
| `scopes` | array of string | yes |  |
| `send` | boolean | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/capabilities \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/service-status`

Customer-safe availability

#### Responses

GET /v1/service-status responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/service-status response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `database` | boolean | yes |  |
| `environment` | string (live, test) | yes |  |
| `provider` | string | yes |  |
| `status` | string (ok, degraded) | yes |  |
| `status_page` | string or null | no |  |
| `version` | string | yes |  |
| `worker_beat_age_s` | integer or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/service-status \ -H "Authorization: Bearer ffa_test_..."`
```

## extractions

- `GET /v1/classifications` Classifications, newest first
- `POST /v1/classifications` Classify a received fax or a document into one of your document types, or abstain
- `GET /v1/classifications/{classification_id}` One classification
- `GET /v1/document-summaries` Summaries, newest first
- `POST /v1/document-summaries` Summarise a received fax or a document; every sentence cites its pages
- `GET /v1/document-summaries/{summary_id}` One summary
- `GET /v1/extraction-schemas` Your extraction schemas
- `POST /v1/extraction-schemas` Save a versioned extraction schema (the same name again is the next version)
- `GET /v1/extraction-schemas/{schema_id}` One schema version
- `GET /v1/extractions` Extractions, newest first
- `POST /v1/extractions` Read a received fax or a document: OCR per page, then fields against a schema
- `GET /v1/extractions/{extraction_id}` One extraction with its corrections
- `POST /v1/extractions/{extraction_id}/corrections` Record a reviewer's correction of one field (stored beside the extraction, never merged)

### GET `/v1/classifications`

Classifications, newest first

#### Parameters

GET /v1/classifications parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `inbox_item_id` | query | string or null | no |  |
| `document_id` | query | string or null | no |  |
| `cursor` | query | string or null | no |  |
| `limit` | query | integer | no | Default `50` . |

#### Responses

GET /v1/classifications responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/classifications response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Extraction | yes |  |
| `next_cursor` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/classifications \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/classifications`

Classify a received fax or a document into one of your document types, or abstain

#### Request body application/json, required

POST /v1/classifications request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `abstain_below` | number | no |  |
| `document_id` | string or null | no |  |
| `document_types` | array of string | yes |  |
| `inbox_item_id` | string or null | no |  |
| `max_pages` | integer or null | no |  |
| `strict` | boolean | no | Refuse with page_limit_exceeded when the document has more pages than would be read, instead of reading the first ones and warning. |
| `strong_model_if_below` | number | no |  |

#### Responses

POST /v1/classifications responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/classifications response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | string or null | yes |  |
| `confidence` | number or null | yes |  |
| `corrections` | array of object or null | no |  |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `currency` | string | yes |  |
| `document_id` | string | yes |  |
| `document_pages` | integer | yes | The document's page count. Above pages_processed on a completed row means the cap left pages unread; output.truncated and a warning say so. |
| `environment` | string (live, test) | yes |  |
| `error_code` | string or null | yes |  |
| `id` | string | yes |  |
| `inbox_item_id` | string or null | yes |  |
| `kind` | string (extract, classify, summarize) | yes |  |
| `models` | object | yes |  |
| `options` | object | yes |  |
| `output` | object or null | yes |  |
| `pages` | array of object ExtractionPage | yes |  |
| `pages_escalated` | integer | yes |  |
| `pages_processed` | integer | yes |  |
| `pages_requested` | integer | yes |  |
| `price_micro` | integer | yes |  |
| `provider_cost_micro` | integer | yes |  |
| `schema` | object or null | no |  |
| `schema_id` | string or null | yes |  |
| `started_at` | string or null | yes |  |
| `status` | string (pending, queued, running, completed, failed) | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/classifications \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/classifications/{classification_id}`

One classification

#### Parameters

GET /v1/classifications/{classification_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `classification_id` | path | string | yes |  |

#### Responses

GET /v1/classifications/{classification_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/classifications/{classification_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | string or null | yes |  |
| `confidence` | number or null | yes |  |
| `corrections` | array of object or null | no |  |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `currency` | string | yes |  |
| `document_id` | string | yes |  |
| `document_pages` | integer | yes | The document's page count. Above pages_processed on a completed row means the cap left pages unread; output.truncated and a warning say so. |
| `environment` | string (live, test) | yes |  |
| `error_code` | string or null | yes |  |
| `id` | string | yes |  |
| `inbox_item_id` | string or null | yes |  |
| `kind` | string (extract, classify, summarize) | yes |  |
| `models` | object | yes |  |
| `options` | object | yes |  |
| `output` | object or null | yes |  |
| `pages` | array of object ExtractionPage | yes |  |
| `pages_escalated` | integer | yes |  |
| `pages_processed` | integer | yes |  |
| `pages_requested` | integer | yes |  |
| `price_micro` | integer | yes |  |
| `provider_cost_micro` | integer | yes |  |
| `schema` | object or null | no |  |
| `schema_id` | string or null | yes |  |
| `started_at` | string or null | yes |  |
| `status` | string (pending, queued, running, completed, failed) | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/classifications/CLASSIFICATION_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/document-summaries`

Summaries, newest first

#### Parameters

GET /v1/document-summaries parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `inbox_item_id` | query | string or null | no |  |
| `document_id` | query | string or null | no |  |
| `cursor` | query | string or null | no |  |
| `limit` | query | integer | no | Default `50` . |

#### Responses

GET /v1/document-summaries responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/document-summaries response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Extraction | yes |  |
| `next_cursor` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/document-summaries \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/document-summaries`

Summarise a received fax or a document; every sentence cites its pages

#### Request body application/json, required

POST /v1/document-summaries request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `document_id` | string or null | no |  |
| `inbox_item_id` | string or null | no |  |
| `max_pages` | integer or null | no |  |
| `strict` | boolean | no | Refuse with page_limit_exceeded when the document has more pages than would be read, instead of reading the first ones and warning. |
| `strong_model_if_below` | number | no |  |

#### Responses

POST /v1/document-summaries responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/document-summaries response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | string or null | yes |  |
| `confidence` | number or null | yes |  |
| `corrections` | array of object or null | no |  |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `currency` | string | yes |  |
| `document_id` | string | yes |  |
| `document_pages` | integer | yes | The document's page count. Above pages_processed on a completed row means the cap left pages unread; output.truncated and a warning say so. |
| `environment` | string (live, test) | yes |  |
| `error_code` | string or null | yes |  |
| `id` | string | yes |  |
| `inbox_item_id` | string or null | yes |  |
| `kind` | string (extract, classify, summarize) | yes |  |
| `models` | object | yes |  |
| `options` | object | yes |  |
| `output` | object or null | yes |  |
| `pages` | array of object ExtractionPage | yes |  |
| `pages_escalated` | integer | yes |  |
| `pages_processed` | integer | yes |  |
| `pages_requested` | integer | yes |  |
| `price_micro` | integer | yes |  |
| `provider_cost_micro` | integer | yes |  |
| `schema` | object or null | no |  |
| `schema_id` | string or null | yes |  |
| `started_at` | string or null | yes |  |
| `status` | string (pending, queued, running, completed, failed) | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/document-summaries \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/document-summaries/{summary_id}`

One summary

#### Parameters

GET /v1/document-summaries/{summary_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `summary_id` | path | string | yes |  |

#### Responses

GET /v1/document-summaries/{summary_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/document-summaries/{summary_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | string or null | yes |  |
| `confidence` | number or null | yes |  |
| `corrections` | array of object or null | no |  |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `currency` | string | yes |  |
| `document_id` | string | yes |  |
| `document_pages` | integer | yes | The document's page count. Above pages_processed on a completed row means the cap left pages unread; output.truncated and a warning say so. |
| `environment` | string (live, test) | yes |  |
| `error_code` | string or null | yes |  |
| `id` | string | yes |  |
| `inbox_item_id` | string or null | yes |  |
| `kind` | string (extract, classify, summarize) | yes |  |
| `models` | object | yes |  |
| `options` | object | yes |  |
| `output` | object or null | yes |  |
| `pages` | array of object ExtractionPage | yes |  |
| `pages_escalated` | integer | yes |  |
| `pages_processed` | integer | yes |  |
| `pages_requested` | integer | yes |  |
| `price_micro` | integer | yes |  |
| `provider_cost_micro` | integer | yes |  |
| `schema` | object or null | no |  |
| `schema_id` | string or null | yes |  |
| `started_at` | string or null | yes |  |
| `status` | string (pending, queued, running, completed, failed) | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/document-summaries/SUMMARY_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/extraction-schemas`

Your extraction schemas

#### Responses

GET /v1/extraction-schemas responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/extraction-schemas response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object ExtractionSchema | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/extraction-schemas \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/extraction-schemas`

Save a versioned extraction schema (the same name again is the next version)

#### Request body application/json, required

POST /v1/extraction-schemas request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string or null | no |  |
| `name` | string | yes |  |
| `schema` | object | yes |  |

#### Responses

POST /v1/extraction-schemas responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/extraction-schemas response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `description` | string or null | yes |  |
| `id` | string | yes |  |
| `name` | string | yes |  |
| `schema` | object | yes |  |
| `status` | string | yes |  |
| `version` | integer | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/extraction-schemas \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/extraction-schemas/{schema_id}`

One schema version

#### Parameters

GET /v1/extraction-schemas/{schema_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `schema_id` | path | string | yes |  |

#### Responses

GET /v1/extraction-schemas/{schema_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/extraction-schemas/{schema_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `description` | string or null | yes |  |
| `id` | string | yes |  |
| `name` | string | yes |  |
| `schema` | object | yes |  |
| `status` | string | yes |  |
| `version` | integer | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/extraction-schemas/SCHEMA_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/extractions`

Extractions, newest first

#### Parameters

GET /v1/extractions parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `inbox_item_id` | query | string or null | no |  |
| `document_id` | query | string or null | no |  |
| `cursor` | query | string or null | no |  |
| `limit` | query | integer | no | Default `50` . |

#### Responses

GET /v1/extractions responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/extractions response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Extraction | yes |  |
| `next_cursor` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/extractions \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/extractions`

Read a received fax or a document: OCR per page, then fields against a schema

#### Request body application/json, required

POST /v1/extractions request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `document_id` | string or null | no |  |
| `inbox_item_id` | string or null | no |  |
| `max_pages` | integer or null | no |  |
| `schema` | object or null | no | A JSON Schema object of string, number, boolean or date fields with descriptions. |
| `schema_id` | string or null | no |  |
| `strict` | boolean | no | Refuse with page_limit_exceeded when the document has more pages than would be read, instead of reading the first ones and warning. |
| `strong_model_if_below` | number | no |  |

#### Responses

POST /v1/extractions responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/extractions response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | string or null | yes |  |
| `confidence` | number or null | yes |  |
| `corrections` | array of object or null | no |  |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `currency` | string | yes |  |
| `document_id` | string | yes |  |
| `document_pages` | integer | yes | The document's page count. Above pages_processed on a completed row means the cap left pages unread; output.truncated and a warning say so. |
| `environment` | string (live, test) | yes |  |
| `error_code` | string or null | yes |  |
| `id` | string | yes |  |
| `inbox_item_id` | string or null | yes |  |
| `kind` | string (extract, classify, summarize) | yes |  |
| `models` | object | yes |  |
| `options` | object | yes |  |
| `output` | object or null | yes |  |
| `pages` | array of object ExtractionPage | yes |  |
| `pages_escalated` | integer | yes |  |
| `pages_processed` | integer | yes |  |
| `pages_requested` | integer | yes |  |
| `price_micro` | integer | yes |  |
| `provider_cost_micro` | integer | yes |  |
| `schema` | object or null | no |  |
| `schema_id` | string or null | yes |  |
| `started_at` | string or null | yes |  |
| `status` | string (pending, queued, running, completed, failed) | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/extractions \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/extractions/{extraction_id}`

One extraction with its corrections

#### Parameters

GET /v1/extractions/{extraction_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `extraction_id` | path | string | yes |  |

#### Responses

GET /v1/extractions/{extraction_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/extractions/{extraction_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | string or null | yes |  |
| `confidence` | number or null | yes |  |
| `corrections` | array of object or null | no |  |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `currency` | string | yes |  |
| `document_id` | string | yes |  |
| `document_pages` | integer | yes | The document's page count. Above pages_processed on a completed row means the cap left pages unread; output.truncated and a warning say so. |
| `environment` | string (live, test) | yes |  |
| `error_code` | string or null | yes |  |
| `id` | string | yes |  |
| `inbox_item_id` | string or null | yes |  |
| `kind` | string (extract, classify, summarize) | yes |  |
| `models` | object | yes |  |
| `options` | object | yes |  |
| `output` | object or null | yes |  |
| `pages` | array of object ExtractionPage | yes |  |
| `pages_escalated` | integer | yes |  |
| `pages_processed` | integer | yes |  |
| `pages_requested` | integer | yes |  |
| `price_micro` | integer | yes |  |
| `provider_cost_micro` | integer | yes |  |
| `schema` | object or null | no |  |
| `schema_id` | string or null | yes |  |
| `started_at` | string or null | yes |  |
| `status` | string (pending, queued, running, completed, failed) | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/extractions/EXTRACTION_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/extractions/{extraction_id}/corrections`

Record a reviewer's correction of one field (stored beside the extraction, never merged)

#### Parameters

POST /v1/extractions/{extraction_id}/corrections parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `extraction_id` | path | string | yes |  |

#### Request body application/json, required

POST /v1/extractions/{extraction_id}/corrections request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `field` | string or null | no |  |
| `note` | string or null | no |  |
| `value` | any | no |  |

#### Responses

POST /v1/extractions/{extraction_id}/corrections responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/extractions/{extraction_id}/corrections response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `extraction_id` | string | yes |  |
| `field` | string | yes |  |
| `id` | string | yes |  |
| `note` | string or null | yes |  |
| `value` | any | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/extractions/EXTRACTION_ID/corrections \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

## numbers

- `GET /v1/coverage` Where we send and where we host numbers
- `GET /v1/number-inventory` Fax-capable numbers for sale
- `POST /v1/number-orders` Buy a number (the first month is held now, charged on activation)
- `GET /v1/number-orders/{order_id}` Read a number order
- `GET /v1/numbers` Your numbers
- `GET /v1/numbers/{number_id}` One number
- `PATCH /v1/numbers/{number_id}` Label and inbound route of a number
- `POST /v1/numbers/{number_id}/release-requests` Release a number (confirm with the number itself; 30-day quarantine follows)
- `GET /v1/port-orders` Port orders and port-out requests
- `POST /v1/port-orders` Request a port-in (handled with you)
- `GET /v1/port-orders/{port_id}` One port order
- `POST /v1/port-out-requests` Note a port-out of one of your numbers
- `POST /v1/portability-checks` Can these numbers port in
- `POST /v1/sender-verifications` Verify a number of yours as a sender (only numbers you own)

### GET `/v1/coverage`

Where we send and where we host numbers

#### Responses

GET /v1/coverage responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/coverage response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `coverage_version` | string or null | yes |  |
| `excluded` | object | yes |  |
| `generated_at` | string or null | yes |  |
| `inbound` | object | yes |  |
| `note` | string or null | yes |  |
| `orderable_now` | array of string | yes |  |
| `outbound` | object | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/coverage \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/number-inventory`

Fax-capable numbers for sale

#### Parameters

GET /v1/number-inventory parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `country` | query | string | no | Default `"US"` . |
| `locality` | query | string or null | no |  |
| `type` | query | string (local, toll_free) | no | Default `"local"` . |
| `limit` | query | integer | no | Default `10` . |

#### Responses

GET /v1/number-inventory responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/number-inventory response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | string | yes |  |
| `items` | array of object InventoryNumber | yes |  |
| `locality` | string or null | yes |  |
| `note` | string | yes |  |
| `number_type` | string | yes |  |
| `recurring_period` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/number-inventory \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/number-orders`

Buy a number (the first month is held now, charged on activation)

#### Request body application/json, required

POST /v1/number-orders request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `e164` | string | yes | A number from GET /v1/number-inventory, E.164. |
| `inbound_webhook_id` | string or null | no | The webhook that receives fax.received for this number (default: all). |
| `label` | string or null | no |  |
| `project_id` | string or null | no | Inbound faxes are filed under this project. |

#### Responses

POST /v1/number-orders responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/number-orders response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | string or null | yes |  |
| `country` | string or null | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `e164` | string or null | yes |  |
| `environment` | string (live, test) | yes |  |
| `error` | string or null | yes |  |
| `first_month_hold_micro` | integer | yes | Held now, captured when the number activates. |
| `id` | string | yes |  |
| `number` | object Number or null | yes |  |
| `number_id` | string or null | yes |  |
| `number_type` | string or null | yes |  |
| `provider` | string | yes |  |
| `recurring_charge_micro` | integer | yes | Charged every month on the activation day. |
| `recurring_period` | string | yes |  |
| `status` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/number-orders \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/number-orders/{order_id}`

Read a number order

#### Parameters

GET /v1/number-orders/{order_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `order_id` | path | string | yes |  |

#### Responses

GET /v1/number-orders/{order_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/number-orders/{order_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | string or null | yes |  |
| `country` | string or null | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `e164` | string or null | yes |  |
| `environment` | string (live, test) | yes |  |
| `error` | string or null | yes |  |
| `first_month_hold_micro` | integer | yes | Held now, captured when the number activates. |
| `id` | string | yes |  |
| `number` | object Number or null | yes |  |
| `number_id` | string or null | yes |  |
| `number_type` | string or null | yes |  |
| `provider` | string | yes |  |
| `recurring_charge_micro` | integer | yes | Charged every month on the activation day. |
| `recurring_period` | string | yes |  |
| `status` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/number-orders/ORDER_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/numbers`

Your numbers

#### Parameters

GET /v1/numbers parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `include_released` | query | boolean | no | Default `false` . |

#### Responses

GET /v1/numbers responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/numbers response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Number | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/numbers \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/numbers/{number_id}`

One number

#### Parameters

GET /v1/numbers/{number_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `number_id` | path | string | yes |  |

#### Responses

GET /v1/numbers/{number_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/numbers/{number_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `activated_at` | string or null | yes |  |
| `country` | string | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `e164` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `inbound_status` | string | yes |  |
| `inbound_webhook_id` | string or null | yes |  |
| `label` | string or null | yes |  |
| `locality` | string or null | yes |  |
| `monthly_micro` | integer | yes |  |
| `number_type` | string | yes |  |
| `order_id` | string or null | yes |  |
| `project_id` | string or null | yes |  |
| `provider` | string | yes |  |
| `released_at` | string or null | yes |  |
| `renews_at` | string or null | yes |  |
| `status` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/numbers/NUMBER_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### PATCH `/v1/numbers/{number_id}`

Label and inbound route of a number

#### Parameters

PATCH /v1/numbers/{number_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `number_id` | path | string | yes |  |

#### Request body application/json, required

PATCH /v1/numbers/{number_id} request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `inbound_webhook_id` | string or null | no |  |
| `label` | string or null | no |  |
| `project_id` | string or null | no |  |

#### Responses

PATCH /v1/numbers/{number_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

PATCH /v1/numbers/{number_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `activated_at` | string or null | yes |  |
| `country` | string | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `e164` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `inbound_status` | string | yes |  |
| `inbound_webhook_id` | string or null | yes |  |
| `label` | string or null | yes |  |
| `locality` | string or null | yes |  |
| `monthly_micro` | integer | yes |  |
| `number_type` | string | yes |  |
| `order_id` | string or null | yes |  |
| `project_id` | string or null | yes |  |
| `provider` | string | yes |  |
| `released_at` | string or null | yes |  |
| `renews_at` | string or null | yes |  |
| `status` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/numbers/NUMBER_ID \ -X PATCH \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/numbers/{number_id}/release-requests`

Release a number (confirm with the number itself; 30-day quarantine follows)

#### Parameters

POST /v1/numbers/{number_id}/release-requests parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `number_id` | path | string | yes |  |

#### Request body application/json, required

POST /v1/numbers/{number_id}/release-requests request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `confirm` | string or null | no | The number itself, typed out, to confirm. |

#### Responses

POST /v1/numbers/{number_id}/release-requests responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/numbers/{number_id}/release-requests response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `activated_at` | string or null | yes |  |
| `country` | string | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `e164` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `inbound_status` | string | yes |  |
| `inbound_webhook_id` | string or null | yes |  |
| `label` | string or null | yes |  |
| `locality` | string or null | yes |  |
| `monthly_micro` | integer | yes |  |
| `number_type` | string | yes |  |
| `order_id` | string or null | yes |  |
| `project_id` | string or null | yes |  |
| `provider` | string | yes |  |
| `released_at` | string or null | yes |  |
| `renews_at` | string or null | yes |  |
| `status` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/numbers/NUMBER_ID/release-requests \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/port-orders`

Port orders and port-out requests

#### Responses

GET /v1/port-orders responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/port-orders response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object PortOrder | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/port-orders \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/port-orders`

Request a port-in (handled with you)

#### Request body application/json, required

POST /v1/port-orders request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `note` | string or null | no |  |
| `numbers` | array of string | yes |  |

#### Responses

POST /v1/port-orders responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/port-orders response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `direction` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `milestones` | array of object | yes |  |
| `numbers` | array of string | yes |  |
| `provider` | string | yes |  |
| `request` | object | yes |  |
| `status` | string | yes |  |
| `updated_at` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/port-orders \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/port-orders/{port_id}`

One port order

#### Parameters

GET /v1/port-orders/{port_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `port_id` | path | string | yes |  |

#### Responses

GET /v1/port-orders/{port_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/port-orders/{port_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `direction` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `milestones` | array of object | yes |  |
| `numbers` | array of string | yes |  |
| `provider` | string | yes |  |
| `request` | object | yes |  |
| `status` | string | yes |  |
| `updated_at` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/port-orders/PORT_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/port-out-requests`

Note a port-out of one of your numbers

#### Request body application/json, required

POST /v1/port-out-requests request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `note` | string or null | no |  |
| `number_id` | string | yes |  |

#### Responses

POST /v1/port-out-requests responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/port-out-requests response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `direction` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `milestones` | array of object | yes |  |
| `numbers` | array of string | yes |  |
| `provider` | string | yes |  |
| `request` | object | yes |  |
| `status` | string | yes |  |
| `updated_at` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/port-out-requests \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/portability-checks`

Can these numbers port in

#### Request body application/json, required

POST /v1/portability-checks request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `numbers` | array of string | yes |  |

#### Responses

POST /v1/portability-checks responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/portability-checks response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checked_at` | string | yes |  |
| `items` | array of object | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/portability-checks \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/sender-verifications`

Verify a number of yours as a sender (only numbers you own)

#### Request body application/json, required

POST /v1/sender-verifications request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string | yes | A number your organization owns, E.164. |

#### Responses

POST /v1/sender-verifications responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/sender-verifications response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `from` | string | yes |  |
| `id` | string | yes |  |
| `method` | string | yes |  |
| `number_id` | string or null | yes |  |
| `status` | string | yes |  |
| `verified_at` | string or null | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/sender-verifications \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

## documents

- `GET /v1/documents` List documents, newest first
- `POST /v1/documents` Create an immutable document from an upload or from text
- `DELETE /v1/documents/{document_id}` Delete a document (its bytes and previews)
- `GET /v1/documents/{document_id}` Read a document's hash, pages and validation state
- `GET /v1/documents/{document_id}/content` The PDF bytes behind a signed URL (no API key)
- `GET /v1/documents/{document_id}/download` A short-lived signed download URL
- `GET /v1/documents/{document_id}/pages` Rendered pages with signed preview URLs
- `GET /v1/documents/{document_id}/pages/{page_number}/content` A page PNG behind a signed URL (no API key)
- `GET /v1/documents/{document_id}/validation` Validation warnings
- `POST /v1/uploads` Create a bounded upload session
- `DELETE /v1/uploads/{upload_id}` Cancel an incomplete upload
- `POST /v1/uploads/{upload_id}/complete` Finalize an upload (size and hash checked)
- `PUT /v1/uploads/{upload_id}/content` Send the bytes to a signed upload URL (no API key)

### GET `/v1/documents`

List documents, newest first

#### Parameters

GET /v1/documents parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `cursor` | query | string or null | no |  |
| `limit` | query | integer | no | Default `50` . |

#### Responses

GET /v1/documents responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/documents response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Document | yes |  |
| `next_cursor` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/documents \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/documents`

Create an immutable document from an upload or from text

#### Request body application/json, required

POST /v1/documents request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filename` | string or null | no |  |
| `html` | string or null | no | HTML rendered to PDF by a headless browser with scripts off and no network: inline CSS and data: images print, external resources are counted as blocked. US letter unless @page says otherwise. At most 2 MiB. |
| `markdown` | string or null | no | Markdown (headings, lists, emphasis, code) rendered to PDF. |
| `text` | string or null | no | Plain text rendered to a letter PDF. |
| `upload_id` | string or null | no |  |

#### Responses

POST /v1/documents responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/documents response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content_type` | string | yes |  |
| `created_at` | string | yes |  |
| `deleted_at` | string or null | yes |  |
| `environment` | string (live, test) | yes |  |
| `expires_at` | string or null | yes |  |
| `filename` | string | yes |  |
| `id` | string | yes |  |
| `page_count` | integer | yes |  |
| `render_reason` | string or null | yes |  |
| `render_status` | string | yes |  |
| `sha256` | string | yes |  |
| `size_bytes` | integer | yes |  |
| `source` | string | yes |  |
| `status` | string | yes |  |
| `upload_id` | string or null | yes |  |
| `validation` | object | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/documents \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### DELETE `/v1/documents/{document_id}`

Delete a document (its bytes and previews)

#### Parameters

DELETE /v1/documents/{document_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `document_id` | path | string | yes |  |

#### Responses

DELETE /v1/documents/{document_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

DELETE /v1/documents/{document_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | boolean | no |  |
| `id` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/documents/DOCUMENT_ID \ -X DELETE \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/documents/{document_id}`

Read a document's hash, pages and validation state

#### Parameters

GET /v1/documents/{document_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `document_id` | path | string | yes |  |

#### Responses

GET /v1/documents/{document_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/documents/{document_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content_type` | string | yes |  |
| `created_at` | string | yes |  |
| `deleted_at` | string or null | yes |  |
| `environment` | string (live, test) | yes |  |
| `expires_at` | string or null | yes |  |
| `filename` | string | yes |  |
| `id` | string | yes |  |
| `page_count` | integer | yes |  |
| `render_reason` | string or null | yes |  |
| `render_status` | string | yes |  |
| `sha256` | string | yes |  |
| `size_bytes` | integer | yes |  |
| `source` | string | yes |  |
| `status` | string | yes |  |
| `upload_id` | string or null | yes |  |
| `validation` | object | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/documents/DOCUMENT_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/documents/{document_id}/content`

The PDF bytes behind a signed URL (no API key)

#### Parameters

GET /v1/documents/{document_id}/content parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `document_id` | path | string | yes |  |
| `exp` | query | string or null | no |  |
| `sig` | query | string or null | no |  |

#### Responses

GET /v1/documents/{document_id}/content responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Example

```
`curl https://api.faxforagents.com/v1/documents/DOCUMENT_ID/content \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/documents/{document_id}/download`

A short-lived signed download URL

#### Parameters

GET /v1/documents/{document_id}/download parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `document_id` | path | string | yes |  |

#### Responses

GET /v1/documents/{document_id}/download responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/documents/{document_id}/download response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content_type` | string | yes |  |
| `expires_at` | string | yes |  |
| `url` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/documents/DOCUMENT_ID/download \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/documents/{document_id}/pages`

Rendered pages with signed preview URLs

#### Parameters

GET /v1/documents/{document_id}/pages parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `document_id` | path | string | yes |  |

#### Responses

GET /v1/documents/{document_id}/pages responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/documents/{document_id}/pages response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `document_id` | string | yes |  |
| `items` | array of object PagePreview | yes |  |
| `page_count` | integer | yes |  |
| `render_reason` | string or null | yes |  |
| `render_status` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/documents/DOCUMENT_ID/pages \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/documents/{document_id}/pages/{page_number}/content`

A page PNG behind a signed URL (no API key)

#### Parameters

GET /v1/documents/{document_id}/pages/{page_number}/content parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `document_id` | path | string | yes |  |
| `page_number` | path | integer | yes |  |
| `exp` | query | string or null | no |  |
| `sig` | query | string or null | no |  |

#### Responses

GET /v1/documents/{document_id}/pages/{page_number}/content responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Example

```
`curl https://api.faxforagents.com/v1/documents/DOCUMENT_ID/pages/PAGE_NUMBER/content \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/documents/{document_id}/validation`

Validation warnings

#### Parameters

GET /v1/documents/{document_id}/validation parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `document_id` | path | string | yes |  |

#### Responses

GET /v1/documents/{document_id}/validation responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/documents/{document_id}/validation response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `page_count` | integer | yes |  |
| `render_reason` | string or null | yes |  |
| `render_status` | string | yes |  |
| `status` | string | yes |  |
| `warnings` | array of object | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/documents/DOCUMENT_ID/validation \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/uploads`

Create a bounded upload session

#### Request body application/json, required

POST /v1/uploads request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content_type` | string | no | application/pdf, image/png, image/jpeg or image/tiff. An image becomes 8-bit gray letter pages, since fax is monochrome. A frame wider than it is tall is rotated. A frame above 300 dpi letter is downsampled. Every TIFF frame is a page. PNG and JPEG take the first frame. The bytes must be the declared type. |
| `filename` | string | yes |  |
| `size_bytes` | integer | yes |  |

#### Responses

POST /v1/uploads responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/uploads response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | string or null | yes |  |
| `content_type` | string | yes |  |
| `created_at` | string | yes |  |
| `declared_size` | integer | yes |  |
| `expires_at` | string | yes |  |
| `filename` | string | yes |  |
| `id` | string | yes |  |
| `received_size` | integer | yes |  |
| `sha256` | string or null | yes |  |
| `status` | string | yes |  |
| `upload_method` | string or null | no |  |
| `upload_url` | string or null | no |  |
| `upload_url_expires_at` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/uploads \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### DELETE `/v1/uploads/{upload_id}`

Cancel an incomplete upload

#### Parameters

DELETE /v1/uploads/{upload_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `upload_id` | path | string | yes |  |

#### Responses

DELETE /v1/uploads/{upload_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

DELETE /v1/uploads/{upload_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | boolean | no |  |
| `id` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/uploads/UPLOAD_ID \ -X DELETE \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/uploads/{upload_id}/complete`

Finalize an upload (size and hash checked)

#### Parameters

POST /v1/uploads/{upload_id}/complete parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `upload_id` | path | string | yes |  |

#### Request body application/json, required

POST /v1/uploads/{upload_id}/complete request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sha256` | string or null | no | Optional: fail if the bytes differ. |

#### Responses

POST /v1/uploads/{upload_id}/complete responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/uploads/{upload_id}/complete response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | string or null | yes |  |
| `content_type` | string | yes |  |
| `created_at` | string | yes |  |
| `declared_size` | integer | yes |  |
| `expires_at` | string | yes |  |
| `filename` | string | yes |  |
| `id` | string | yes |  |
| `received_size` | integer | yes |  |
| `sha256` | string or null | yes |  |
| `status` | string | yes |  |
| `upload_method` | string or null | no |  |
| `upload_url` | string or null | no |  |
| `upload_url_expires_at` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/uploads/UPLOAD_ID/complete \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### PUT `/v1/uploads/{upload_id}/content`

Send the bytes to a signed upload URL (no API key)

#### Parameters

PUT /v1/uploads/{upload_id}/content parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `upload_id` | path | string | yes |  |
| `exp` | query | string or null | no |  |
| `sig` | query | string or null | no |  |

#### Responses

PUT /v1/uploads/{upload_id}/content responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

PUT /v1/uploads/{upload_id}/content response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | string or null | yes |  |
| `content_type` | string | yes |  |
| `created_at` | string | yes |  |
| `declared_size` | integer | yes |  |
| `expires_at` | string | yes |  |
| `filename` | string | yes |  |
| `id` | string | yes |  |
| `received_size` | integer | yes |  |
| `sha256` | string or null | yes |  |
| `status` | string | yes |  |
| `upload_method` | string or null | no |  |
| `upload_url` | string or null | no |  |
| `upload_url_expires_at` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/uploads/UPLOAD_ID/content \ -X PUT \ -H "Authorization: Bearer ffa_test_..."`
```

## events

- `GET /v1/events` Events for reconciliation, oldest first from the cursor

### GET `/v1/events`

Events for reconciliation, oldest first from the cursor

#### Parameters

GET /v1/events parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `type` | query | string or null | no |  |
| `cursor` | query | string or null | no | The cursor from the previous page (opaque). |
| `limit` | query | integer | no | Default `100` . |

#### Responses

GET /v1/events responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/events response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Event | yes |  |
| `next_cursor` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/events \ -H "Authorization: Bearer ffa_test_..."`
```

## quotes

- `POST /v1/fax-quotes` Price an exact document to one destination
- `GET /v1/fax-quotes/{quote_id}` Read a quote

### POST `/v1/fax-quotes`

Price an exact document to one destination

#### Request body application/json, required

POST /v1/fax-quotes request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cover` | object or null | no | Cover sheet fields: to_name, from_name, subject, message. Counts as a page. |
| `document_id` | string | yes |  |
| `from` | string or null | no | A number you own; omit for the shared pool. |
| `to` | string | yes | Destination in E.164, for example +12025550123. |

#### Responses

POST /v1/fax-quotes responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/fax-quotes response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `authorization_required` | boolean | yes |  |
| `billable_pages` | integer | yes |  |
| `consumed_by_job_id` | string or null | yes |  |
| `cover` | object or null | yes |  |
| `cover_pages` | integer | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `document_id` | string | yes |  |
| `document_pages` | integer | yes |  |
| `document_sha256` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `expired` | boolean | yes |  |
| `expires_at` | string | yes |  |
| `from` | string or null | no |  |
| `id` | string | yes |  |
| `per_page_micro` | integer | no |  |
| `price_version` | string | yes |  |
| `route` | string | yes |  |
| `route_label` | string | no |  |
| `to` | string | yes |  |
| `warnings` | array of object | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/fax-quotes \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/fax-quotes/{quote_id}`

Read a quote

#### Parameters

GET /v1/fax-quotes/{quote_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `quote_id` | path | string | yes |  |

#### Responses

GET /v1/fax-quotes/{quote_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/fax-quotes/{quote_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `authorization_required` | boolean | yes |  |
| `billable_pages` | integer | yes |  |
| `consumed_by_job_id` | string or null | yes |  |
| `cover` | object or null | yes |  |
| `cover_pages` | integer | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `document_id` | string | yes |  |
| `document_pages` | integer | yes |  |
| `document_sha256` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `expired` | boolean | yes |  |
| `expires_at` | string | yes |  |
| `from` | string or null | no |  |
| `id` | string | yes |  |
| `per_page_micro` | integer | no |  |
| `price_version` | string | yes |  |
| `route` | string | yes |  |
| `route_label` | string | no |  |
| `to` | string | yes |  |
| `warnings` | array of object | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/fax-quotes/QUOTE_ID \ -H "Authorization: Bearer ffa_test_..."`
```

## faxes

- `GET /v1/faxes` List fax jobs, newest first
- `POST /v1/faxes` Send a quoted fax (Idempotency-Key recommended)
- `GET /v1/faxes/{fax_id}` Read a fax job (with evidence once delivered)
- `GET /v1/faxes/{fax_id}/attempts` Attempt history
- `POST /v1/faxes/{fax_id}/cancel` Cancel if still possible (best effort once sending)
- `GET /v1/faxes/{fax_id}/events` Ordered events of one fax
- `GET /v1/faxes/{fax_id}/receipt` Delivery evidence as a receipt (JSON)

### GET `/v1/faxes`

List fax jobs, newest first

#### Parameters

GET /v1/faxes parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `state` | query | string or null | no |  |
| `cursor` | query | string or null | no |  |
| `limit` | query | integer | no | Default `50` . |

#### Responses

GET /v1/faxes responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/faxes response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object FaxJob | yes |  |
| `next_cursor` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/faxes \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/faxes`

Send a quoted fax (Idempotency-Key recommended)

#### Request body application/json, required

M9: an approved request authorizes the send; without one a quote that needs authorization is evaluated against the caller's delegated policies.

POST /v1/faxes request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `approval_id` | string or null | no | An approved approval request bound to this quote. Consumed by this one send. |
| `client_reference` | string or null | no |  |
| `quote_id` | string | yes |  |

#### Responses

POST /v1/faxes responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/faxes response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `attempt_count` | integer | yes |  |
| `billable_pages` | integer | yes |  |
| `cancel_requested_at` | string or null | yes |  |
| `captured_micro` | integer | yes |  |
| `client_reference` | string or null | yes |  |
| `completed_at` | string or null | yes |  |
| `cover_pages` | integer | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `direction` | string | yes |  |
| `document_id` | string | yes |  |
| `document_sha256` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `evidence` | object or null | no | The carrier's evidence once delivered or partial; null before. |
| `failure_code` | string or null | yes |  |
| `from` | string or null | no |  |
| `id` | string | yes |  |
| `pages_sent` | integer | yes |  |
| `provider` | string | yes |  |
| `provider_ref` | string or null | yes |  |
| `quote_id` | string or null | yes |  |
| `route` | string | yes |  |
| `state` | string (queued, active, partial, failed, unknown, delivered) | yes |  |
| `to` | string | yes |  |
| `transmitted_sha256` | string or null | yes |  |
| `updated_at` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/faxes \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/faxes/{fax_id}`

Read a fax job (with evidence once delivered)

#### Parameters

GET /v1/faxes/{fax_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `fax_id` | path | string | yes |  |

#### Responses

GET /v1/faxes/{fax_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/faxes/{fax_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `attempt_count` | integer | yes |  |
| `billable_pages` | integer | yes |  |
| `cancel_requested_at` | string or null | yes |  |
| `captured_micro` | integer | yes |  |
| `client_reference` | string or null | yes |  |
| `completed_at` | string or null | yes |  |
| `cover_pages` | integer | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `direction` | string | yes |  |
| `document_id` | string | yes |  |
| `document_sha256` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `evidence` | object or null | no | The carrier's evidence once delivered or partial; null before. |
| `failure_code` | string or null | yes |  |
| `from` | string or null | no |  |
| `id` | string | yes |  |
| `pages_sent` | integer | yes |  |
| `provider` | string | yes |  |
| `provider_ref` | string or null | yes |  |
| `quote_id` | string or null | yes |  |
| `route` | string | yes |  |
| `state` | string (queued, active, partial, failed, unknown, delivered) | yes |  |
| `to` | string | yes |  |
| `transmitted_sha256` | string or null | yes |  |
| `updated_at` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/faxes/FAX_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/faxes/{fax_id}/attempts`

Attempt history

#### Parameters

GET /v1/faxes/{fax_id}/attempts parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `fax_id` | path | string | yes |  |

#### Responses

GET /v1/faxes/{fax_id}/attempts responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/faxes/{fax_id}/attempts response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Attempt | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/faxes/FAX_ID/attempts \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/faxes/{fax_id}/cancel`

Cancel if still possible (best effort once sending)

#### Parameters

POST /v1/faxes/{fax_id}/cancel parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `fax_id` | path | string | yes |  |

#### Responses

POST /v1/faxes/{fax_id}/cancel responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/faxes/{fax_id}/cancel response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `attempt_count` | integer | yes |  |
| `billable_pages` | integer | yes |  |
| `cancel_requested_at` | string or null | yes |  |
| `captured_micro` | integer | yes |  |
| `client_reference` | string or null | yes |  |
| `completed_at` | string or null | yes |  |
| `cover_pages` | integer | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `direction` | string | yes |  |
| `document_id` | string | yes |  |
| `document_sha256` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `evidence` | object or null | no | The carrier's evidence once delivered or partial; null before. |
| `failure_code` | string or null | yes |  |
| `from` | string or null | no |  |
| `id` | string | yes |  |
| `pages_sent` | integer | yes |  |
| `provider` | string | yes |  |
| `provider_ref` | string or null | yes |  |
| `quote_id` | string or null | yes |  |
| `route` | string | yes |  |
| `state` | string (queued, active, partial, failed, unknown, delivered) | yes |  |
| `to` | string | yes |  |
| `transmitted_sha256` | string or null | yes |  |
| `updated_at` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/faxes/FAX_ID/cancel \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/faxes/{fax_id}/events`

Ordered events of one fax

#### Parameters

GET /v1/faxes/{fax_id}/events parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `fax_id` | path | string | yes |  |

#### Responses

GET /v1/faxes/{fax_id}/events responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/faxes/{fax_id}/events response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Event | yes |  |
| `next_cursor` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/faxes/FAX_ID/events \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/faxes/{fax_id}/receipt`

Delivery evidence as a receipt (JSON)

#### Parameters

GET /v1/faxes/{fax_id}/receipt parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `fax_id` | path | string | yes |  |

#### Responses

GET /v1/faxes/{fax_id}/receipt responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/faxes/{fax_id}/receipt response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `attempts` | array of object Attempt | yes |  |
| `billable_pages` | integer | yes |  |
| `captured_micro` | integer | yes |  |
| `completed_at` | string or null | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `document_sha256` | string | yes |  |
| `evidence` | object or null | yes |  |
| `failure_code` | string or null | yes |  |
| `fax_job_id` | string | yes |  |
| `from` | string or null | no |  |
| `generated_at` | string | yes |  |
| `note` | string | yes |  |
| `pages_sent` | integer | yes |  |
| `provider` | string | yes |  |
| `state` | string | yes |  |
| `to` | string | yes |  |
| `transmitted_sha256` | string or null | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/faxes/FAX_ID/receipt \ -H "Authorization: Bearer ffa_test_..."`
```

## inbox

- `GET /v1/inbox` Received faxes, newest first (metadata only)
- `DELETE /v1/inbox/{inbox_id}` Delete a received fax
- `GET /v1/inbox/{inbox_id}` One received fax with its text as data
- `PATCH /v1/inbox/{inbox_id}` Mark a received fax read or archived
- `GET /v1/inbox/{inbox_id}/content` The received PDF behind a signed URL (no API key)
- `GET /v1/inbox/{inbox_id}/download` A short-lived signed link to the received PDF

### GET `/v1/inbox`

Received faxes, newest first (metadata only)

#### Parameters

GET /v1/inbox parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `cursor` | query | string or null | no |  |
| `limit` | query | integer | no | Default `50` . |
| `status` | query | string (received, read, archived) or null | no |  |

#### Responses

GET /v1/inbox responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/inbox response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object faxforagents__api__routes__inbox__InboxItem | yes |  |
| `next_cursor` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/inbox \ -H "Authorization: Bearer ffa_test_..."`
```

### DELETE `/v1/inbox/{inbox_id}`

Delete a received fax

#### Parameters

DELETE /v1/inbox/{inbox_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `inbox_id` | path | string | yes |  |

#### Responses

DELETE /v1/inbox/{inbox_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

DELETE /v1/inbox/{inbox_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | boolean | no |  |
| `id` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/inbox/INBOX_ID \ -X DELETE \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/inbox/{inbox_id}`

One received fax with its text as data

#### Parameters

GET /v1/inbox/{inbox_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `inbox_id` | path | string | yes |  |

#### Responses

GET /v1/inbox/{inbox_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/inbox/{inbox_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | no |  |
| `document` | object or null | no |  |
| `document_id` | string or null | yes |  |
| `duration_secs` | integer or null | no |  |
| `environment` | string (live, test) | no |  |
| `expires_at` | string or null | no |  |
| `extraction_id` | string or null | no |  |
| `from` | string or null | no |  |
| `id` | string | yes |  |
| `media_status` | string | no |  |
| `note` | string or null | no |  |
| `number_id` | string or null | no |  |
| `pages` | integer | yes |  |
| `partial_content` | boolean | no |  |
| `project_id` | string or null | no |  |
| `provider` | string | no |  |
| `read_at` | string or null | no |  |
| `received_at` | string | yes |  |
| `status` | string | yes |  |
| `text` | string or null | no |  |
| `to` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/inbox/INBOX_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### PATCH `/v1/inbox/{inbox_id}`

Mark a received fax read or archived

#### Parameters

PATCH /v1/inbox/{inbox_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `inbox_id` | path | string | yes |  |

#### Request body application/json, required

PATCH /v1/inbox/{inbox_id} request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string (received, read, archived) or null | no |  |

#### Responses

PATCH /v1/inbox/{inbox_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

PATCH /v1/inbox/{inbox_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | no |  |
| `document_id` | string or null | yes |  |
| `duration_secs` | integer or null | no |  |
| `environment` | string (live, test) | no |  |
| `expires_at` | string or null | no |  |
| `from` | string or null | no |  |
| `id` | string | yes |  |
| `media_status` | string | no |  |
| `note` | string or null | no |  |
| `number_id` | string or null | no |  |
| `pages` | integer | yes |  |
| `partial_content` | boolean | no |  |
| `project_id` | string or null | no |  |
| `provider` | string | no |  |
| `read_at` | string or null | no |  |
| `received_at` | string | yes |  |
| `status` | string | yes |  |
| `to` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/inbox/INBOX_ID \ -X PATCH \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/inbox/{inbox_id}/content`

The received PDF behind a signed URL (no API key)

#### Parameters

GET /v1/inbox/{inbox_id}/content parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `inbox_id` | path | string | yes |  |
| `exp` | query | string or null | no |  |
| `sig` | query | string or null | no |  |

#### Responses

GET /v1/inbox/{inbox_id}/content responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Example

```
`curl https://api.faxforagents.com/v1/inbox/INBOX_ID/content \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/inbox/{inbox_id}/download`

A short-lived signed link to the received PDF

#### Parameters

GET /v1/inbox/{inbox_id}/download parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `inbox_id` | path | string | yes |  |

#### Responses

GET /v1/inbox/{inbox_id}/download responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/inbox/{inbox_id}/download response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content_type` | string | yes |  |
| `expires_at` | string | yes |  |
| `url` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/inbox/INBOX_ID/download \ -H "Authorization: Bearer ffa_test_..."`
```

## members

- `GET /v1/invitations` Open invitations
- `POST /v1/invitations` Invite someone by email (a link that works for 7 days)
- `DELETE /v1/invitations/{invitation_id}` Withdraw an invitation
- `GET /v1/members` The organization's members
- `DELETE /v1/members/{member_id}` Remove a member (owner)
- `PATCH /v1/members/{member_id}` Change a member's role

### GET `/v1/invitations`

Open invitations

#### Responses

GET /v1/invitations responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/invitations response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Invitation | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/invitations \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/invitations`

Invite someone by email (a link that works for 7 days)

#### Request body application/json, required

POST /v1/invitations request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `role` | string (owner, admin, member, viewer) | no |  |

#### Responses

POST /v1/invitations responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/invitations response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accepted_at` | string or null | yes |  |
| `created_at` | string | yes |  |
| `email` | string | yes |  |
| `expires_at` | string | yes |  |
| `id` | string | yes |  |
| `invited_by` | string | yes |  |
| `role` | string (owner, admin, member, viewer) | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/invitations \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### DELETE `/v1/invitations/{invitation_id}`

Withdraw an invitation

#### Parameters

DELETE /v1/invitations/{invitation_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `invitation_id` | path | string | yes |  |

#### Responses

DELETE /v1/invitations/{invitation_id} responses

| Status | Meaning |
| --- | --- |
| `204` | Successful Response |
| `422` | Validation Error |

#### Example

```
`curl https://api.faxforagents.com/v1/invitations/INVITATION_ID \ -X DELETE \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/members`

The organization's members

#### Responses

GET /v1/members responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/members response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Member | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/members \ -H "Authorization: Bearer ffa_test_..."`
```

### DELETE `/v1/members/{member_id}`

Remove a member (owner)

#### Parameters

DELETE /v1/members/{member_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `member_id` | path | string | yes |  |

#### Responses

DELETE /v1/members/{member_id} responses

| Status | Meaning |
| --- | --- |
| `204` | Successful Response |
| `422` | Validation Error |

#### Example

```
`curl https://api.faxforagents.com/v1/members/MEMBER_ID \ -X DELETE \ -H "Authorization: Bearer ffa_test_..."`
```

### PATCH `/v1/members/{member_id}`

Change a member's role

#### Parameters

PATCH /v1/members/{member_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `member_id` | path | string | yes |  |

#### Request body application/json, required

PATCH /v1/members/{member_id} request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | string (owner, admin, member, viewer) or null | no | Required. Optional in the schema so a foreign id is a 404 first. |

#### Responses

PATCH /v1/members/{member_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

PATCH /v1/members/{member_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `email` | string | yes |  |
| `id` | string | yes |  |
| `name` | string or null | yes |  |
| `role` | string (owner, admin, member, viewer) | yes |  |
| `user_id` | string or null | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/members/MEMBER_ID \ -X PATCH \ -H "Authorization: Bearer ffa_test_..."`
```

## one-time-sends

- `GET /v1/one-time-sends/config` Whether one-time sends are open here, and the card and limits an order is priced and checked by

### GET `/v1/one-time-sends/config`

Whether one-time sends are open here, and the card and limits an order is priced and checked by

#### Responses

GET /v1/one-time-sends/config responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/one-time-sends/config response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `aup_url` | string | yes |  |
| `aup_version` | string | yes |  |
| `currency` | string | yes |  |
| `effective_from` | string | yes |  |
| `enabled` | boolean | yes |  |
| `formats` | array of string | yes |  |
| `max_document_pages` | integer | yes |  |
| `max_text_chars` | integer | yes |  |
| `max_upload_bytes` | integer | yes |  |
| `price_version` | string | yes |  |
| `reason` | string or null | no |  |
| `routes` | object | yes |  |
| `terms_url` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/one-time-sends/config \ -H "Authorization: Bearer ffa_test_..."`
```

## organizations

- `GET /v1/organizations` The organizations you belong to
- `GET /v1/organizations/current` The organization you are looking at
- `PATCH /v1/organizations/current` Rename the organization
- `POST /v1/organizations/current/deletion-requests` Ask for the organization and its data to be deleted (owner)
- `POST /v1/organizations/current/export-requests` Ask for an export of the organization's data (owner)

### GET `/v1/organizations`

The organizations you belong to

#### Responses

GET /v1/organizations responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/organizations response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object OrganizationSummary | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/organizations \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/organizations/current`

The organization you are looking at

#### Responses

GET /v1/organizations/current responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/organizations/current response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `id` | string | yes |  |
| `members` | integer | yes |  |
| `name` | string | yes |  |
| `role` | string (owner, admin, member, viewer) or null | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/organizations/current \ -H "Authorization: Bearer ffa_test_..."`
```

### PATCH `/v1/organizations/current`

Rename the organization

#### Request body application/json, required

PATCH /v1/organizations/current request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |

#### Responses

PATCH /v1/organizations/current responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

PATCH /v1/organizations/current response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `id` | string | yes |  |
| `members` | integer | yes |  |
| `name` | string | yes |  |
| `role` | string (owner, admin, member, viewer) or null | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/organizations/current \ -X PATCH \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/organizations/current/deletion-requests`

Ask for the organization and its data to be deleted (owner)

#### Responses

POST /v1/organizations/current/deletion-requests responses

| Status | Meaning |
| --- | --- |
| `202` | Successful Response |

#### Response fields

POST /v1/organizations/current/deletion-requests response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string (export, deletion) | yes |  |
| `message` | string | yes |  |
| `requested` | boolean | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/organizations/current/deletion-requests \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/organizations/current/export-requests`

Ask for an export of the organization's data (owner)

#### Responses

POST /v1/organizations/current/export-requests responses

| Status | Meaning |
| --- | --- |
| `202` | Successful Response |

#### Response fields

POST /v1/organizations/current/export-requests response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string (export, deletion) | yes |  |
| `message` | string | yes |  |
| `requested` | boolean | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/organizations/current/export-requests \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

## policies

- `GET /v1/policies` List the organization's policies
- `POST /v1/policies` Create a delegated policy (version 1)
- `GET /v1/policies/effective` What the calling key may do on its own, and whether a human is needed otherwise
- `GET /v1/policies/{policy_id}` Read a policy (its current version)
- `PATCH /v1/policies/{policy_id}` Change a policy: a new immutable version
- `GET /v1/policies/{policy_id}/versions` Every version, oldest first
- `POST /v1/policy-evaluations` Dry run: would the calling key's policies allow this send? Never executes

### GET `/v1/policies`

List the organization's policies

#### Responses

GET /v1/policies responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/policies response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Policy | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/policies \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/policies`

Create a delegated policy (version 1)

#### Request body application/json, required

POST /v1/policies request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | no |  |
| `name` | string | yes |  |
| `purpose` | string or null | no | Why this policy exists. Shown, never evaluated. |
| `rules` | object | yes | See the PolicyRules schema in docs/APPROVALS.md. |

#### Responses

POST /v1/policies responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/policies response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `current_version_id` | string or null | yes |  |
| `enabled` | boolean | yes |  |
| `id` | string | yes |  |
| `name` | string | yes |  |
| `purpose` | string or null | yes |  |
| `rules` | object | yes |  |
| `updated_at` | string | yes |  |
| `version` | integer | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/policies \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/policies/effective`

What the calling key may do on its own, and whether a human is needed otherwise

#### Responses

GET /v1/policies/effective responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/policies/effective response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actor` | string | yes |  |
| `approval_required_without_policy` | boolean | yes |  |
| `environment` | string (live, test) | yes |  |
| `policies` | array of object Policy | yes |  |
| `rules_order` | array of string | yes |  |
| `under_policy` | boolean | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/policies/effective \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/policies/{policy_id}`

Read a policy (its current version)

#### Parameters

GET /v1/policies/{policy_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `policy_id` | path | string | yes |  |

#### Responses

GET /v1/policies/{policy_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/policies/{policy_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `current_version_id` | string or null | yes |  |
| `enabled` | boolean | yes |  |
| `id` | string | yes |  |
| `name` | string | yes |  |
| `purpose` | string or null | yes |  |
| `rules` | object | yes |  |
| `updated_at` | string | yes |  |
| `version` | integer | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/policies/POLICY_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### PATCH `/v1/policies/{policy_id}`

Change a policy: a new immutable version

#### Parameters

PATCH /v1/policies/{policy_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `policy_id` | path | string | yes |  |

#### Request body application/json, required

PATCH /v1/policies/{policy_id} request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean or null | no |  |
| `name` | string or null | no |  |
| `purpose` | string or null | no |  |
| `rules` | object or null | no |  |

#### Responses

PATCH /v1/policies/{policy_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

PATCH /v1/policies/{policy_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `current_version_id` | string or null | yes |  |
| `enabled` | boolean | yes |  |
| `id` | string | yes |  |
| `name` | string | yes |  |
| `purpose` | string or null | yes |  |
| `rules` | object | yes |  |
| `updated_at` | string | yes |  |
| `version` | integer | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/policies/POLICY_ID \ -X PATCH \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/policies/{policy_id}/versions`

Every version, oldest first

#### Parameters

GET /v1/policies/{policy_id}/versions parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `policy_id` | path | string | yes |  |

#### Responses

GET /v1/policies/{policy_id}/versions responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/policies/{policy_id}/versions response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object PolicyVersion | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/policies/POLICY_ID/versions \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/policy-evaluations`

Dry run: would the calling key's policies allow this send? Never executes

#### Request body application/json, required

POST /v1/policy-evaluations request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `document_id` | string or null | no | Or plan: this document ... |
| `from` | string or null | no |  |
| `quote_id` | string or null | no | Evaluate an existing quote. |
| `to` | string or null | no | ... to this E.164 destination. |

#### Responses

POST /v1/policy-evaluations responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/policy-evaluations response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `decision` | string | yes |  |
| `denials` | array of object | yes |  |
| `executed` | boolean | no |  |
| `plan` | object | yes |  |
| `policy_id` | string or null | yes |  |
| `policy_name` | string or null | yes |  |
| `policy_version_id` | string or null | yes |  |
| `reason` | string | yes |  |
| `rule` | string or null | yes |  |
| `version` | integer or null | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/policy-evaluations \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

## sandbox

- `DELETE /v1/sandbox/data` Reset this organization's test data
- `POST /v1/sandbox/inbound-faxes` Create a synthetic inbound fax (the same pipeline as a real one)
- `GET /v1/sandbox/scenarios` The scenario catalog and active fixtures
- `POST /v1/sandbox/scenarios` Select the outcome of the next sends

### DELETE `/v1/sandbox/data`

Reset this organization's test data

#### Responses

DELETE /v1/sandbox/data responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

DELETE /v1/sandbox/data response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | object | yes |  |
| `reset` | boolean | yes |  |
| `wallet_available_micro` | integer | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/sandbox/data \ -X DELETE \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/sandbox/inbound-faxes`

Create a synthetic inbound fax (the same pipeline as a real one)

A synthetic PDF goes through ``inbox.service.receive_now``: the private document, the inbox item, the ``fax.received`` event with its download reference, exactly as a carrier delivery (M8).

#### Request body application/json, required

POST /v1/sandbox/inbound-faxes request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string or null | no |  |
| `pages` | integer | no |  |
| `partial_content` | boolean | no | Rehearse a cut-off transmission. |
| `to` | string | yes |  |

#### Responses

POST /v1/sandbox/inbound-faxes responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/sandbox/inbound-faxes response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | no |  |
| `document_id` | string or null | yes |  |
| `from` | string or null | no |  |
| `id` | string | yes |  |
| `note` | string or null | no |  |
| `pages` | integer | yes |  |
| `received_at` | string | yes |  |
| `status` | string | yes |  |
| `to` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/sandbox/inbound-faxes \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/sandbox/scenarios`

The scenario catalog and active fixtures

#### Responses

GET /v1/sandbox/scenarios responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/sandbox/scenarios response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `destinations` | array of object | yes |  |
| `fixtures` | array of object SandboxFixture | yes |  |
| `scenarios` | array of object | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/sandbox/scenarios \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/sandbox/scenarios`

Select the outcome of the next sends

#### Request body application/json, required

POST /v1/sandbox/scenarios request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `destination` | string or null | no | Apply to one destination; omit for every send. |
| `scenario` | string | yes |  |

#### Responses

POST /v1/sandbox/scenarios responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/sandbox/scenarios response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `destination` | string or null | yes |  |
| `expires_at` | string | yes |  |
| `id` | string | yes |  |
| `scenario` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/sandbox/scenarios \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

## webhooks

- `GET /v1/webhook-deliveries` Delivery attempts (no payload secrets)
- `POST /v1/webhook-deliveries/{delivery_id}/replay` Replay the event with the same event id
- `GET /v1/webhooks` List webhooks
- `POST /v1/webhooks` Register a destination (secret shown once)
- `DELETE /v1/webhooks/{webhook_id}` Remove a destination
- `PATCH /v1/webhooks/{webhook_id}` Change url, filters or pause
- `POST /v1/webhooks/{webhook_id}/rotate-secret` New secret; the old one signs too for 24 hours
- `POST /v1/webhooks/{webhook_id}/test` Send a signed webhook.test event to this destination

### GET `/v1/webhook-deliveries`

Delivery attempts (no payload secrets)

#### Parameters

GET /v1/webhook-deliveries parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `webhook_id` | query | string or null | no |  |
| `event_id` | query | string or null | no |  |
| `cursor` | query | string or null | no |  |
| `limit` | query | integer | no | Default `50` . |

#### Responses

GET /v1/webhook-deliveries responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

GET /v1/webhook-deliveries response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Delivery | yes |  |
| `next_cursor` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/webhook-deliveries \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/webhook-deliveries/{delivery_id}/replay`

Replay the event with the same event id

#### Parameters

POST /v1/webhook-deliveries/{delivery_id}/replay parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `delivery_id` | path | string | yes |  |

#### Responses

POST /v1/webhook-deliveries/{delivery_id}/replay responses

| Status | Meaning |
| --- | --- |
| `202` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/webhook-deliveries/{delivery_id}/replay response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `attempt` | integer | yes |  |
| `created_at` | string | yes |  |
| `delivered_at` | string or null | yes |  |
| `duration_ms` | integer or null | yes |  |
| `error` | string or null | yes |  |
| `event_id` | string | yes |  |
| `event_type` | string | yes |  |
| `id` | string | yes |  |
| `next_attempt_at` | string or null | yes |  |
| `replay_of` | string or null | yes |  |
| `response_status` | integer or null | yes |  |
| `schedule_s` | array of integer | yes |  |
| `status` | string | yes |  |
| `webhook_id` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/webhook-deliveries/DELIVERY_ID/replay \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/webhooks`

List webhooks

#### Responses

GET /v1/webhooks responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |

#### Response fields

GET /v1/webhooks response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Webhook | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/webhooks \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/webhooks`

Register a destination (secret shown once)

#### Request body application/json, required

POST /v1/webhooks request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string or null | no |  |
| `event_types` | array of string or null | no | Empty or omitted: every event type. |
| `url` | string | yes |  |

#### Responses

POST /v1/webhooks responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/webhooks response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `description` | string or null | yes |  |
| `event_types` | array of string | yes |  |
| `id` | string | yes |  |
| `previous_secret_expires_at` | string or null | yes |  |
| `secret` | string | yes | whsec_... Shown once. Verify webhook-signature with it. |
| `status` | string | yes |  |
| `updated_at` | string | yes |  |
| `url` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/webhooks \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### DELETE `/v1/webhooks/{webhook_id}`

Remove a destination

#### Parameters

DELETE /v1/webhooks/{webhook_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `webhook_id` | path | string | yes |  |

#### Responses

DELETE /v1/webhooks/{webhook_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

DELETE /v1/webhooks/{webhook_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | boolean | no |  |
| `id` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/webhooks/WEBHOOK_ID \ -X DELETE \ -H "Authorization: Bearer ffa_test_..."`
```

### PATCH `/v1/webhooks/{webhook_id}`

Change url, filters or pause

#### Parameters

PATCH /v1/webhooks/{webhook_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `webhook_id` | path | string | yes |  |

#### Request body application/json, required

PATCH /v1/webhooks/{webhook_id} request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string or null | no |  |
| `event_types` | array of string or null | no |  |
| `status` | string (active, paused) or null | no |  |
| `url` | string or null | no |  |

#### Responses

PATCH /v1/webhooks/{webhook_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

PATCH /v1/webhooks/{webhook_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `description` | string or null | yes |  |
| `event_types` | array of string | yes |  |
| `id` | string | yes |  |
| `previous_secret_expires_at` | string or null | yes |  |
| `status` | string | yes |  |
| `updated_at` | string | yes |  |
| `url` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/webhooks/WEBHOOK_ID \ -X PATCH \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/webhooks/{webhook_id}/rotate-secret`

New secret; the old one signs too for 24 hours

#### Parameters

POST /v1/webhooks/{webhook_id}/rotate-secret parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `webhook_id` | path | string | yes |  |

#### Responses

POST /v1/webhooks/{webhook_id}/rotate-secret responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/webhooks/{webhook_id}/rotate-secret response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `description` | string or null | yes |  |
| `event_types` | array of string | yes |  |
| `id` | string | yes |  |
| `previous_secret_expires_at` | string or null | yes |  |
| `secret` | string | yes | whsec_... Shown once. Verify webhook-signature with it. |
| `status` | string | yes |  |
| `updated_at` | string | yes |  |
| `url` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/webhooks/WEBHOOK_ID/rotate-secret \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/webhooks/{webhook_id}/test`

Send a signed webhook.test event to this destination

#### Parameters

POST /v1/webhooks/{webhook_id}/test parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `webhook_id` | path | string | yes |  |

#### Responses

POST /v1/webhooks/{webhook_id}/test responses

| Status | Meaning |
| --- | --- |
| `202` | Successful Response |
| `422` | Validation Error |

#### Response fields

POST /v1/webhooks/{webhook_id}/test response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `correlation_id` | string or null | yes |  |
| `created_at` | string | yes |  |
| `data` | object | yes |  |
| `environment` | string (live, test) | yes |  |
| `fax_job_id` | string or null | yes |  |
| `id` | string | yes |  |
| `org_id` | string | yes |  |
| `project_id` | string or null | yes |  |
| `resource_id` | string | yes |  |
| `resource_type` | string | yes |  |
| `schema_version` | integer | yes |  |
| `type` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/webhooks/WEBHOOK_ID/test \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

## Schemas

149 named objects, as the API sends and accepts them.

### Accepted

Accepted fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `organization` | object OrganizationSummary | yes |  |

### Agent

Agent fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `budget_id` | string or null | yes |  |
| `budgets` | array of object | yes |  |
| `contact_email` | string or null | yes |  |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `disabled_at` | string or null | yes |  |
| `enabled` | boolean | yes |  |
| `id` | string | yes |  |
| `keys` | array of object ApiKey | yes |  |
| `name` | string | yes |  |
| `policy_ids` | array of string | yes |  |
| `project_id` | string or null | yes |  |
| `purpose` | string or null | yes |  |
| `status` | string | yes |  |
| `updated_at` | string | yes |  |

### AgentActivity

AgentActivity fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | string | yes |  |
| `actor` | string | yes |  |
| `correlation_id` | string or null | yes |  |
| `created_at` | string | yes |  |
| `data` | object | yes |  |
| `id` | string | yes |  |
| `resource_id` | string or null | yes |  |
| `resource_type` | string | yes |  |

### AgentActivityPage

AgentActivityPage fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object AgentActivity | yes |  |
| `next_cursor` | string or null | no |  |

### AgentCreate

AgentCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contact_email` | string or null | no | Where decided approvals are mailed. |
| `name` | string | yes |  |
| `policy_ids` | array of string | no |  |
| `purpose` | string or null | no | Shown to humans, never evaluated. |

### AgentKeyCreate

AgentKeyCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `environment` | string (live, test) | no |  |
| `expires_in_days` | integer or null | no |  |
| `label` | string | no |  |
| `scopes` | array of string or null | no | Omit for the default agent set. Never approval:decide, key:admin, policy:admin, agent:admin. |

### AgentList

AgentList fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Agent | yes |  |

### AgentUpdate

AgentUpdate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contact_email` | string or null | no |  |
| `enabled` | boolean or null | no | false revokes every key of the agent. |
| `name` | string or null | no |  |
| `policy_ids` | array of string or null | no |  |
| `purpose` | string or null | no |  |

### ApiKey

ApiKey fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_id` | string or null | yes |  |
| `created_at` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `expires_at` | string or null | yes |  |
| `id` | string | yes |  |
| `label` | string | yes |  |
| `last_used_at` | string or null | yes |  |
| `prefix` | string | yes |  |
| `project_id` | string or null | yes |  |
| `revoked_at` | string or null | yes |  |
| `rotated_from_id` | string or null | yes |  |
| `scopes` | array of string | yes |  |

### ApiKeyCreate

ApiKeyCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `environment` | string (live, test) | no |  |
| `expires_in_days` | integer or null | no |  |
| `label` | string | yes |  |
| `scopes` | array of string or null | no | Omit for the default agent set; '*' for all. |

### ApiKeyList

ApiKeyList fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object ApiKey | yes |  |

### ApiKeyWithSecret

ApiKeyWithSecret fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_id` | string or null | yes |  |
| `created_at` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `expires_at` | string or null | yes |  |
| `id` | string | yes |  |
| `label` | string | yes |  |
| `last_used_at` | string or null | yes |  |
| `prefix` | string | yes |  |
| `project_id` | string or null | yes |  |
| `revoked_at` | string or null | yes |  |
| `rotated_from_id` | string or null | yes |  |
| `scopes` | array of string | yes |  |
| `secret` | string | yes | Shown once. Store it now; it cannot be read back. |

### ApprovalDecision

ApprovalDecision fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string or null | no |  |

### ApprovalRequest

ApprovalRequest fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `bound` | object | yes |  |
| `consumed_by_job_id` | string or null | yes |  |
| `created_at` | string | yes |  |
| `decided_at` | string or null | yes |  |
| `decided_by` | string or null | yes |  |
| `expires_at` | string or null | yes |  |
| `id` | string | yes |  |
| `kind` | string (send, help) | yes |  |
| `message` | string or null | yes |  |
| `notified` | boolean or null | no | On creation: whether the organization was mailed. false when the request repeats a pending one or the organization's daily cap of request mails is reached; the request is still shown in the dashboard. |
| `quote_id` | string or null | yes |  |
| `reason` | string or null | yes |  |
| `requested_by` | string | yes |  |
| `status` | string (pending, approved, rejected, revoked, expired) | yes |  |

### ApprovalRequestCreate

ApprovalRequestCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fax_job_id` | string or null | no |  |
| `kind` | string (send, help) | no |  |
| `message` | string or null | no | What the person should know (kind help). Shown as data. |
| `quote_id` | string or null | no | The quote to bind (kind send). |

### ApprovalRequestPage

ApprovalRequestPage fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object ApprovalRequest | yes |  |
| `next_cursor` | string or null | no |  |

### Attempt

Attempt fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `attempt_number` | integer | yes |  |
| `error` | string or null | yes |  |
| `evidence` | object or null | yes |  |
| `failure_code` | string or null | yes |  |
| `fax_job_id` | string | yes |  |
| `finished_at` | string or null | yes |  |
| `id` | string | yes |  |
| `pages_sent` | integer | yes |  |
| `provider` | string | yes |  |
| `provider_ref` | string or null | yes |  |
| `started_at` | string | yes |  |
| `status` | string | yes |  |

### AttemptPage

AttemptPage fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Attempt | yes |  |

### AutoTopup

AutoTopup fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `created_at` | string | yes |  |
| `daily_cap_micro` | integer | yes |  |
| `disabled_at` | string or null | yes |  |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `last_attempt_at` | string or null | yes |  |
| `payment_method_saved` | boolean | yes |  |
| `setup_session_id` | string or null | yes |  |
| `setup_url` | string or null | no | Where to save the card while status is pending_setup. |
| `status` | string (pending_setup, active, disabled) | yes |  |
| `threshold_micro` | integer | yes |  |
| `updated_at` | string | yes |  |

### AutoTopupCreate

AutoTopupCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes | Whole dollars, 10 to 1000 USD. |
| `daily_cap_micro` | integer | yes | Never more than this per UTC day. |
| `threshold_micro` | integer | yes | Top up when the available balance drops below this. |

### AutoTopupList

AutoTopupList fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object AutoTopup | yes |  |

### Balance

Balance fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `available_micro` | integer | yes |  |
| `currency` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `held_micro` | integer | yes |  |

### BillingSettings

BillingSettings fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `billing_email` | string or null | yes |  |
| `disputed` | boolean | yes |  |
| `low_balance_active` | boolean | yes |  |
| `low_balance_threshold_micro` | integer | yes |  |
| `org_id` | string | yes |  |
| `stripe_customer` | boolean | yes |  |
| `workspace` | boolean | yes |  |

### BillingSettingsPatch

BillingSettingsPatch fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `billing_email` | string or null | no |  |
| `low_balance_threshold_micro` | integer or null | no |  |

### Budget

Budget fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_id` | string or null | yes |  |
| `created_at` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `limit_micro` | integer | yes |  |
| `period` | string (daily, monthly) | yes |  |
| `project_id` | string or null | yes |  |
| `remaining_micro` | integer | yes |  |
| `resets_at` | string | yes |  |
| `scope` | string (organization, project, agent) | yes |  |
| `spent_micro` | integer | yes |  |
| `status` | string (active, disabled) | yes |  |
| `updated_at` | string | yes |  |

### BudgetCreate

BudgetCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_id` | string or null | no |  |
| `limit_micro` | integer | yes |  |
| `period` | string (daily, monthly) | yes |  |
| `project_id` | string or null | no |  |
| `scope` | string (organization, project, agent) | no |  |

### BudgetList

BudgetList fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Budget | yes |  |

### BudgetPatch

BudgetPatch fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit_micro` | integer or null | no |  |
| `status` | string (active, disabled) or null | no |  |

### Capabilities

Capabilities fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `approvals` | boolean | yes |  |
| `environment` | string (live, test) | yes |  |
| `formats` | array of string | yes |  |
| `limits` | object | yes |  |
| `max_pages` | integer | yes |  |
| `max_upload_bytes` | integer | yes |  |
| `numbers` | boolean | yes |  |
| `one_time` | object | yes |  |
| `price_version` | string | yes |  |
| `provider` | string | yes |  |
| `rates` | object | yes |  |
| `receive` | boolean | yes |  |
| `routes` | array of string | yes |  |
| `scopes` | array of string | yes |  |
| `send` | boolean | yes |  |

### ClassificationCreate

ClassificationCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `abstain_below` | number | no |  |
| `document_id` | string or null | no |  |
| `document_types` | array of string | yes |  |
| `inbox_item_id` | string or null | no |  |
| `max_pages` | integer or null | no |  |
| `strict` | boolean | no | Refuse with page_limit_exceeded when the document has more pages than would be read, instead of reading the first ones and warning. |
| `strong_model_if_below` | number | no |  |

### Correction

Correction fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `extraction_id` | string | yes |  |
| `field` | string | yes |  |
| `id` | string | yes |  |
| `note` | string or null | yes |  |
| `value` | any | yes |  |

### CorrectionCreate

CorrectionCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `field` | string or null | no |  |
| `note` | string or null | no |  |
| `value` | any | no |  |

### Coverage

Coverage fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `coverage_version` | string or null | yes |  |
| `excluded` | object | yes |  |
| `generated_at` | string or null | yes |  |
| `inbound` | object | yes |  |
| `note` | string or null | yes |  |
| `orderable_now` | array of string | yes |  |
| `outbound` | object | yes |  |

### Deleted

Deleted fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | boolean | no |  |
| `id` | string | yes |  |

### Delivery

Delivery fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `attempt` | integer | yes |  |
| `created_at` | string | yes |  |
| `delivered_at` | string or null | yes |  |
| `duration_ms` | integer or null | yes |  |
| `error` | string or null | yes |  |
| `event_id` | string | yes |  |
| `event_type` | string | yes |  |
| `id` | string | yes |  |
| `next_attempt_at` | string or null | yes |  |
| `replay_of` | string or null | yes |  |
| `response_status` | integer or null | yes |  |
| `schedule_s` | array of integer | yes |  |
| `status` | string | yes |  |
| `webhook_id` | string | yes |  |

### DeliveryPage

DeliveryPage fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Delivery | yes |  |
| `next_cursor` | string or null | no |  |

### Document

Document fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content_type` | string | yes |  |
| `created_at` | string | yes |  |
| `deleted_at` | string or null | yes |  |
| `environment` | string (live, test) | yes |  |
| `expires_at` | string or null | yes |  |
| `filename` | string | yes |  |
| `id` | string | yes |  |
| `page_count` | integer | yes |  |
| `render_reason` | string or null | yes |  |
| `render_status` | string | yes |  |
| `sha256` | string | yes |  |
| `size_bytes` | integer | yes |  |
| `source` | string | yes |  |
| `status` | string | yes |  |
| `upload_id` | string or null | yes |  |
| `validation` | object | yes |  |

### DocumentCreate

DocumentCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filename` | string or null | no |  |
| `html` | string or null | no | HTML rendered to PDF by a headless browser with scripts off and no network: inline CSS and data: images print, external resources are counted as blocked. US letter unless @page says otherwise. At most 2 MiB. |
| `markdown` | string or null | no | Markdown (headings, lists, emphasis, code) rendered to PDF. |
| `text` | string or null | no | Plain text rendered to a letter PDF. |
| `upload_id` | string or null | no |  |

### DocumentPage

DocumentPage fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Document | yes |  |
| `next_cursor` | string or null | no |  |

### DocumentPages

DocumentPages fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `document_id` | string | yes |  |
| `items` | array of object PagePreview | yes |  |
| `page_count` | integer | yes |  |
| `render_reason` | string or null | yes |  |
| `render_status` | string | yes |  |

### DocumentValidation

DocumentValidation fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `page_count` | integer | yes |  |
| `render_reason` | string or null | yes |  |
| `render_status` | string | yes |  |
| `status` | string | yes |  |
| `warnings` | array of object | yes |  |

### EffectivePolicies

EffectivePolicies fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actor` | string | yes |  |
| `approval_required_without_policy` | boolean | yes |  |
| `environment` | string (live, test) | yes |  |
| `policies` | array of object Policy | yes |  |
| `rules_order` | array of string | yes |  |
| `under_policy` | boolean | yes |  |

### Event

Event fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `correlation_id` | string or null | yes |  |
| `created_at` | string | yes |  |
| `data` | object | yes |  |
| `environment` | string (live, test) | yes |  |
| `fax_job_id` | string or null | yes |  |
| `id` | string | yes |  |
| `org_id` | string | yes |  |
| `project_id` | string or null | yes |  |
| `resource_id` | string | yes |  |
| `resource_type` | string | yes |  |
| `schema_version` | integer | yes |  |
| `type` | string | yes |  |

### EventPage

EventPage fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Event | yes |  |
| `next_cursor` | string or null | no |  |

### Extraction

Extraction fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | string or null | yes |  |
| `confidence` | number or null | yes |  |
| `corrections` | array of object or null | no |  |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `currency` | string | yes |  |
| `document_id` | string | yes |  |
| `document_pages` | integer | yes | The document's page count. Above pages_processed on a completed row means the cap left pages unread; output.truncated and a warning say so. |
| `environment` | string (live, test) | yes |  |
| `error_code` | string or null | yes |  |
| `id` | string | yes |  |
| `inbox_item_id` | string or null | yes |  |
| `kind` | string (extract, classify, summarize) | yes |  |
| `models` | object | yes |  |
| `options` | object | yes |  |
| `output` | object or null | yes |  |
| `pages` | array of object ExtractionPage | yes |  |
| `pages_escalated` | integer | yes |  |
| `pages_processed` | integer | yes |  |
| `pages_requested` | integer | yes |  |
| `price_micro` | integer | yes |  |
| `provider_cost_micro` | integer | yes |  |
| `schema` | object or null | no |  |
| `schema_id` | string or null | yes |  |
| `started_at` | string or null | yes |  |
| `status` | string (pending, queued, running, completed, failed) | yes |  |

### ExtractionCreate

ExtractionCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `document_id` | string or null | no |  |
| `inbox_item_id` | string or null | no |  |
| `max_pages` | integer or null | no |  |
| `schema` | object or null | no | A JSON Schema object of string, number, boolean or date fields with descriptions. |
| `schema_id` | string or null | no |  |
| `strict` | boolean | no | Refuse with page_limit_exceeded when the document has more pages than would be read, instead of reading the first ones and warning. |
| `strong_model_if_below` | number | no |  |

### ExtractionPage

ExtractionPage fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `confidence` | number | yes |  |
| `escalated` | boolean | no |  |
| `language` | string or null | no |  |
| `model` | string | yes |  |
| `page` | integer | yes |  |
| `status` | string | yes |  |
| `text` | string | yes |  |
| `warnings` | array of string | no |  |

### ExtractionPageList

ExtractionPageList fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Extraction | yes |  |
| `next_cursor` | string or null | no |  |

### ExtractionSchema

ExtractionSchema fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `description` | string or null | yes |  |
| `id` | string | yes |  |
| `name` | string | yes |  |
| `schema` | object | yes |  |
| `status` | string | yes |  |
| `version` | integer | yes |  |

### ExtractionSchemaList

ExtractionSchemaList fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object ExtractionSchema | yes |  |

### FaxCreate

M9: an approved request authorizes the send; without one a quote that needs authorization is evaluated against the caller's delegated policies.

FaxCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `approval_id` | string or null | no | An approved approval request bound to this quote. Consumed by this one send. |
| `client_reference` | string or null | no |  |
| `quote_id` | string | yes |  |

### FaxJob

FaxJob fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `attempt_count` | integer | yes |  |
| `billable_pages` | integer | yes |  |
| `cancel_requested_at` | string or null | yes |  |
| `captured_micro` | integer | yes |  |
| `client_reference` | string or null | yes |  |
| `completed_at` | string or null | yes |  |
| `cover_pages` | integer | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `direction` | string | yes |  |
| `document_id` | string | yes |  |
| `document_sha256` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `evidence` | object or null | no | The carrier's evidence once delivered or partial; null before. |
| `failure_code` | string or null | yes |  |
| `from` | string or null | no |  |
| `id` | string | yes |  |
| `pages_sent` | integer | yes |  |
| `provider` | string | yes |  |
| `provider_ref` | string or null | yes |  |
| `quote_id` | string or null | yes |  |
| `route` | string | yes |  |
| `state` | string (queued, active, partial, failed, unknown, delivered) | yes |  |
| `to` | string | yes |  |
| `transmitted_sha256` | string or null | yes |  |
| `updated_at` | string | yes |  |

### FaxJobPage

FaxJobPage fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object FaxJob | yes |  |
| `next_cursor` | string or null | no |  |

### HTTPValidationError

HTTPValidationError fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | array of object ValidationError | no |  |

### InboxItemDetail

InboxItemDetail fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | no |  |
| `document` | object or null | no |  |
| `document_id` | string or null | yes |  |
| `duration_secs` | integer or null | no |  |
| `environment` | string (live, test) | no |  |
| `expires_at` | string or null | no |  |
| `extraction_id` | string or null | no |  |
| `from` | string or null | no |  |
| `id` | string | yes |  |
| `media_status` | string | no |  |
| `note` | string or null | no |  |
| `number_id` | string or null | no |  |
| `pages` | integer | yes |  |
| `partial_content` | boolean | no |  |
| `project_id` | string or null | no |  |
| `provider` | string | no |  |
| `read_at` | string or null | no |  |
| `received_at` | string | yes |  |
| `status` | string | yes |  |
| `text` | string or null | no |  |
| `to` | string | yes |  |

### InboxPage

InboxPage fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object faxforagents__api__routes__inbox__InboxItem | yes |  |
| `next_cursor` | string or null | no |  |

### InboxUpdate

InboxUpdate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string (received, read, archived) or null | no |  |

### Inventory

Inventory fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | string | yes |  |
| `items` | array of object InventoryNumber | yes |  |
| `locality` | string or null | yes |  |
| `note` | string | yes |  |
| `number_type` | string | yes |  |
| `recurring_period` | string | yes |  |

### InventoryNumber

InventoryNumber fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | string | yes |  |
| `currency` | string | yes |  |
| `e164` | string | yes |  |
| `locality` | string or null | yes |  |
| `monthly_micro` | integer | yes |  |
| `number_type` | string | yes |  |
| `setup_micro` | integer | yes |  |

### Invitation

Invitation fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accepted_at` | string or null | yes |  |
| `created_at` | string | yes |  |
| `email` | string | yes |  |
| `expires_at` | string | yes |  |
| `id` | string | yes |  |
| `invited_by` | string | yes |  |
| `role` | string (owner, admin, member, viewer) | yes |  |

### InvitationCreate

InvitationCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `role` | string (owner, admin, member, viewer) | no |  |

### InvitationList

InvitationList fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Invitation | yes |  |

### Invoice

Invoice fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_due_micro` | integer | yes |  |
| `amount_paid_micro` | integer | yes |  |
| `created_at` | string or null | yes |  |
| `currency` | string | yes |  |
| `hosted_invoice_url` | string or null | yes |  |
| `id` | string | yes |  |
| `invoice_pdf` | string or null | yes |  |
| `number` | string or null | yes |  |
| `status` | string or null | yes |  |
| `subscription_id` | string or null | yes |  |

### InvoicePage

InvoicePage fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Invoice | yes |  |
| `next_cursor` | string or null | no |  |

### LedgerEntry

LedgerEntry fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account` | string | yes |  |
| `amount_micro` | integer | yes |  |
| `created_at` | string | yes |  |
| `id` | string | yes |  |
| `kind` | string | yes |  |
| `memo` | string or null | yes |  |
| `ref_id` | string or null | yes |  |
| `ref_type` | string or null | yes |  |
| `txn_id` | string | yes |  |

### LedgerPage

LedgerPage fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object LedgerEntry | yes |  |
| `next_cursor` | string or null | no |  |

### MagicLinkRequest

MagicLinkRequest fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `next` | string or null | no | An in-app path to open after sign-in. |

### Member

Member fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `email` | string | yes |  |
| `id` | string | yes |  |
| `name` | string or null | yes |  |
| `role` | string (owner, admin, member, viewer) | yes |  |
| `user_id` | string or null | yes |  |

### MemberList

MemberList fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Member | yes |  |

### MemberPatch

MemberPatch fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | string (owner, admin, member, viewer) or null | no | Required. Optional in the schema so a foreign id is a 404 first. |

### Number

Number fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `activated_at` | string or null | yes |  |
| `country` | string | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `e164` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `inbound_status` | string | yes |  |
| `inbound_webhook_id` | string or null | yes |  |
| `label` | string or null | yes |  |
| `locality` | string or null | yes |  |
| `monthly_micro` | integer | yes |  |
| `number_type` | string | yes |  |
| `order_id` | string or null | yes |  |
| `project_id` | string or null | yes |  |
| `provider` | string | yes |  |
| `released_at` | string or null | yes |  |
| `renews_at` | string or null | yes |  |
| `status` | string | yes |  |

### NumberList

NumberList fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Number | yes |  |

### NumberOrder

NumberOrder fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | string or null | yes |  |
| `country` | string or null | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `e164` | string or null | yes |  |
| `environment` | string (live, test) | yes |  |
| `error` | string or null | yes |  |
| `first_month_hold_micro` | integer | yes | Held now, captured when the number activates. |
| `id` | string | yes |  |
| `number` | object Number or null | yes |  |
| `number_id` | string or null | yes |  |
| `number_type` | string or null | yes |  |
| `provider` | string | yes |  |
| `recurring_charge_micro` | integer | yes | Charged every month on the activation day. |
| `recurring_period` | string | yes |  |
| `status` | string | yes |  |

### NumberOrderCreate

NumberOrderCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `e164` | string | yes | A number from GET /v1/number-inventory, E.164. |
| `inbound_webhook_id` | string or null | no | The webhook that receives fax.received for this number (default: all). |
| `label` | string or null | no |  |
| `project_id` | string or null | no | Inbound faxes are filed under this project. |

### NumberUpdate

NumberUpdate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `inbound_webhook_id` | string or null | no |  |
| `label` | string or null | no |  |
| `project_id` | string or null | no |  |

### OneTimeConfig

What the public send page and an agent read before an order: whether the product is open here, the card the order will be priced from (present only while open), the document limits and the policy the sender accepts. Prices are integer micro-USD; the dollar figure is the client's to format.

OneTimeConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `aup_url` | string | yes |  |
| `aup_version` | string | yes |  |
| `currency` | string | yes |  |
| `effective_from` | string | yes |  |
| `enabled` | boolean | yes |  |
| `formats` | array of string | yes |  |
| `max_document_pages` | integer | yes |  |
| `max_text_chars` | integer | yes |  |
| `max_upload_bytes` | integer | yes |  |
| `price_version` | string | yes |  |
| `reason` | string or null | no |  |
| `routes` | object | yes |  |
| `terms_url` | string | yes |  |

### OneTimeRoute

OneTimeRoute fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cover_included` | boolean | yes |  |
| `extra_page_micro` | integer | yes |  |
| `flat_micro` | integer | yes |  |
| `included_pages` | integer | yes |  |
| `label` | string | yes |  |

### Organization

Organization fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `id` | string | yes |  |
| `members` | integer | yes |  |
| `name` | string | yes |  |
| `role` | string (owner, admin, member, viewer) or null | yes |  |

### OrganizationList

OrganizationList fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object OrganizationSummary | yes |  |

### OrganizationPatch

OrganizationPatch fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |

### OrganizationSummary

OrganizationSummary fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `name` | string | yes |  |
| `role` | string (owner, admin, member, viewer) | yes |  |

### PagePreview

PagePreview fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `height_px` | integer or null | yes |  |
| `page_number` | integer | yes |  |
| `url` | string | yes |  |
| `width_px` | integer or null | yes |  |

### Passkey

Passkey fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `aaguid` | string or null | yes |  |
| `backup_eligible` | boolean | yes |  |
| `created_at` | string | yes |  |
| `id` | string | yes |  |
| `label` | string or null | yes |  |
| `last_used_at` | string or null | yes |  |
| `transports` | array of string or null | yes |  |

### PasskeyList

PasskeyList fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Passkey | yes |  |

### PasskeyLoginVerify

PasskeyLoginVerify fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `credential` | object | yes |  |

### PasskeyRegisterVerify

PasskeyRegisterVerify fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `credential` | object | yes |  |
| `label` | string or null | no |  |

### Policy

Policy fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `current_version_id` | string or null | yes |  |
| `enabled` | boolean | yes |  |
| `id` | string | yes |  |
| `name` | string | yes |  |
| `purpose` | string or null | yes |  |
| `rules` | object | yes |  |
| `updated_at` | string | yes |  |
| `version` | integer | yes |  |

### PolicyCreate

PolicyCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | no |  |
| `name` | string | yes |  |
| `purpose` | string or null | no | Why this policy exists. Shown, never evaluated. |
| `rules` | object | yes | See the PolicyRules schema in docs/APPROVALS.md. |

### PolicyEvaluation

PolicyEvaluation fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `decision` | string | yes |  |
| `denials` | array of object | yes |  |
| `executed` | boolean | no |  |
| `plan` | object | yes |  |
| `policy_id` | string or null | yes |  |
| `policy_name` | string or null | yes |  |
| `policy_version_id` | string or null | yes |  |
| `reason` | string | yes |  |
| `rule` | string or null | yes |  |
| `version` | integer or null | yes |  |

### PolicyEvaluationCreate

PolicyEvaluationCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `document_id` | string or null | no | Or plan: this document ... |
| `from` | string or null | no |  |
| `quote_id` | string or null | no | Evaluate an existing quote. |
| `to` | string or null | no | ... to this E.164 destination. |

### PolicyList

PolicyList fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Policy | yes |  |

### PolicyUpdate

PolicyUpdate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean or null | no |  |
| `name` | string or null | no |  |
| `purpose` | string or null | no |  |
| `rules` | object or null | no |  |

### PolicyVersion

PolicyVersion fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `created_by` | string | yes |  |
| `enabled` | boolean | yes |  |
| `id` | string | yes |  |
| `name` | string | yes |  |
| `policy_id` | string | yes |  |
| `purpose` | string or null | yes |  |
| `rules` | object | yes |  |
| `version` | integer | yes |  |

### PolicyVersionList

PolicyVersionList fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object PolicyVersion | yes |  |

### PortOrder

PortOrder fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `direction` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `milestones` | array of object | yes |  |
| `numbers` | array of string | yes |  |
| `provider` | string | yes |  |
| `request` | object | yes |  |
| `status` | string | yes |  |
| `updated_at` | string | yes |  |

### PortOrderCreate

PortOrderCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `note` | string or null | no |  |
| `numbers` | array of string | yes |  |

### PortOrderList

PortOrderList fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object PortOrder | yes |  |

### PortOutRequestCreate

PortOutRequestCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `note` | string or null | no |  |
| `number_id` | string | yes |  |

### PortabilityCheck

PortabilityCheck fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checked_at` | string | yes |  |
| `items` | array of object | yes |  |

### PortabilityCheckCreate

PortabilityCheckCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `numbers` | array of string | yes |  |

### PortalSession

PortalSession fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expires_at` | string | yes |  |
| `url` | string | yes |  |

### Providers

Providers fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `github` | boolean | yes |  |
| `google` | boolean | yes |  |
| `magic_link` | boolean | no |  |
| `passkeys` | boolean | no |  |

### Quote

Quote fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `authorization_required` | boolean | yes |  |
| `billable_pages` | integer | yes |  |
| `consumed_by_job_id` | string or null | yes |  |
| `cover` | object or null | yes |  |
| `cover_pages` | integer | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `document_id` | string | yes |  |
| `document_pages` | integer | yes |  |
| `document_sha256` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `expired` | boolean | yes |  |
| `expires_at` | string | yes |  |
| `from` | string or null | no |  |
| `id` | string | yes |  |
| `per_page_micro` | integer | no |  |
| `price_version` | string | yes |  |
| `route` | string | yes |  |
| `route_label` | string | no |  |
| `to` | string | yes |  |
| `warnings` | array of object | yes |  |

### QuoteCreate

QuoteCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cover` | object or null | no | Cover sheet fields: to_name, from_name, subject, message. Counts as a page. |
| `document_id` | string | yes |  |
| `from` | string or null | no | A number you own; omit for the shared pool. |
| `to` | string | yes | Destination in E.164, for example +12025550123. |

### Reauth

Reauth fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `credential` | object or null | no |  |
| `method` | string (passkey, magic_link) | yes |  |

### Receipt

Receipt fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `attempts` | array of object Attempt | yes |  |
| `billable_pages` | integer | yes |  |
| `captured_micro` | integer | yes |  |
| `completed_at` | string or null | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `document_sha256` | string | yes |  |
| `evidence` | object or null | yes |  |
| `failure_code` | string or null | yes |  |
| `fax_job_id` | string | yes |  |
| `from` | string or null | no |  |
| `generated_at` | string | yes |  |
| `note` | string | yes |  |
| `pages_sent` | integer | yes |  |
| `provider` | string | yes |  |
| `state` | string | yes |  |
| `to` | string | yes |  |
| `transmitted_sha256` | string or null | yes |  |

### ReleaseRequest

ReleaseRequest fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `confirm` | string or null | no | The number itself, typed out, to confirm. |

### Requested

Requested fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string (export, deletion) | yes |  |
| `message` | string | yes |  |
| `requested` | boolean | yes |  |

### Revoked

Revoked fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `revoked` | integer | yes |  |

### SandboxFixture

SandboxFixture fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `destination` | string or null | yes |  |
| `expires_at` | string | yes |  |
| `id` | string | yes |  |
| `scenario` | string | yes |  |

### SandboxInboundCreate

SandboxInboundCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string or null | no |  |
| `pages` | integer | no |  |
| `partial_content` | boolean | no | Rehearse a cut-off transmission. |
| `to` | string | yes |  |

### SandboxReset

SandboxReset fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | object | yes |  |
| `reset` | boolean | yes |  |
| `wallet_available_micro` | integer | yes |  |

### SandboxScenarioCreate

SandboxScenarioCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `destination` | string or null | no | Apply to one destination; omit for every send. |
| `scenario` | string | yes |  |

### SandboxScenarios

SandboxScenarios fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `destinations` | array of object | yes |  |
| `fixtures` | array of object SandboxFixture | yes |  |
| `scenarios` | array of object | yes |  |

### SchemaCreate

SchemaCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string or null | no |  |
| `name` | string | yes |  |
| `schema` | object | yes |  |

### SenderVerification

SenderVerification fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `from` | string | yes |  |
| `id` | string | yes |  |
| `method` | string | yes |  |
| `number_id` | string or null | yes |  |
| `status` | string | yes |  |
| `verified_at` | string or null | yes |  |

### SenderVerificationCreate

SenderVerificationCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string | yes | A number your organization owns, E.164. |

### Sent

Sent fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | string | yes |  |
| `sent` | boolean | yes |  |

### ServiceStatus

ServiceStatus fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `database` | boolean | yes |  |
| `environment` | string (live, test) | yes |  |
| `provider` | string | yes |  |
| `status` | string (ok, degraded) | yes |  |
| `status_page` | string or null | no |  |
| `version` | string | yes |  |
| `worker_beat_age_s` | integer or null | no |  |

### SessionInfo

SessionInfo fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `auth_method` | string | yes |  |
| `authenticated_at` | string | yes |  |
| `expires_at` | string | yes |  |
| `fresh` | boolean | yes |  |
| `fresh_until` | string | yes |  |
| `id` | string | yes |  |

### SessionList

SessionList fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object SessionOut | yes |  |

### SessionOut

SessionOut fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `auth_method` | string | yes |  |
| `authenticated_at` | string | yes |  |
| `created_at` | string | yes |  |
| `current` | boolean | yes |  |
| `expires_at` | string | yes |  |
| `id` | string | yes |  |
| `ip` | string or null | yes |  |
| `last_seen_at` | string | yes |  |
| `user_agent` | string or null | yes |  |

### SignedUrl

SignedUrl fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content_type` | string | yes |  |
| `expires_at` | string | yes |  |
| `url` | string | yes |  |

### Subscription

Subscription fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cancel_at_period_end` | boolean | yes |  |
| `canceled_at` | string or null | yes |  |
| `created_at` | string | yes |  |
| `current_period_end` | string or null | yes |  |
| `entitled` | boolean | yes |  |
| `id` | string | yes |  |
| `product` | string | yes |  |
| `status` | string | yes |  |
| `stripe_price_id` | string or null | yes |  |
| `stripe_subscription_id` | string | yes |  |
| `updated_at` | string | yes |  |

### SubscriptionCheckout

SubscriptionCheckout fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product` | string | yes |  |
| `stripe_session_id` | string | yes |  |
| `url` | string | yes |  |

### SubscriptionList

SubscriptionList fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Subscription | yes |  |
| `next_cursor` | string or null | no |  |
| `workspace` | boolean | yes |  |

### SummaryCreate

SummaryCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `document_id` | string or null | no |  |
| `inbox_item_id` | string or null | no |  |
| `max_pages` | integer or null | no |  |
| `strict` | boolean | no | Refuse with page_limit_exceeded when the document has more pages than would be read, instead of reading the first ones and warning. |
| `strong_model_if_below` | number | no |  |

### SwitchOrganization

SwitchOrganization fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `org_id` | string | yes |  |

### TopupCreate

TopupCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_usd` | integer | yes | Whole US dollars, 10 to 1000 per session. |

### TopupSession

TopupSession fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `auto_topup_id` | string or null | yes |  |
| `completed_at` | string or null | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `error` | string or null | yes |  |
| `expires_at` | string or null | yes |  |
| `id` | string | yes |  |
| `kind` | string (manual, auto, setup) | yes |  |
| `status` | string (open, completed, expired, canceled, failed) | yes |  |
| `stripe_payment_intent_id` | string or null | yes |  |
| `stripe_session_id` | string or null | yes |  |
| `url` | string or null | no | The hosted Checkout page while the session is open. |

### TopupSessionPage

TopupSessionPage fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object TopupSession | yes |  |
| `next_cursor` | string or null | no |  |

### UploadComplete

UploadComplete fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sha256` | string or null | no | Optional: fail if the bytes differ. |

### UploadCreate

UploadCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content_type` | string | no | application/pdf, image/png, image/jpeg or image/tiff. An image becomes 8-bit gray letter pages, since fax is monochrome. A frame wider than it is tall is rotated. A frame above 300 dpi letter is downsampled. Every TIFF frame is a page. PNG and JPEG take the first frame. The bytes must be the declared type. |
| `filename` | string | yes |  |
| `size_bytes` | integer | yes |  |

### UploadSession

UploadSession fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | string or null | yes |  |
| `content_type` | string | yes |  |
| `created_at` | string | yes |  |
| `declared_size` | integer | yes |  |
| `expires_at` | string | yes |  |
| `filename` | string | yes |  |
| `id` | string | yes |  |
| `received_size` | integer | yes |  |
| `sha256` | string or null | yes |  |
| `status` | string | yes |  |
| `upload_method` | string or null | no |  |
| `upload_url` | string or null | no |  |
| `upload_url_expires_at` | string or null | no |  |

### UsageExport

UsageExport fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content_type` | string | yes |  |
| `created_at` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `expires_at` | string | yes |  |
| `id` | string | yes |  |
| `params` | object | yes |  |
| `row_count` | integer | yes |  |
| `status` | string (ready, expired) | yes |  |
| `url` | string or null | yes |  |

### UsageExportCreate

UsageExportCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string or null | no | ISO date; default 30 days ago. |
| `to` | string or null | no | ISO date; default today. |

### UsageItem

UsageItem fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `day` | string or null | no |  |
| `destination` | string or null | no |  |
| `direction` | string or null | no |  |
| `jobs` | integer | yes |  |
| `pages` | integer | yes |  |
| `project_id` | string or null | no |  |
| `route` | string or null | no |  |

### UsageReport

UsageReport fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `currency` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `from` | string | yes |  |
| `group_by` | array of string | yes |  |
| `items` | array of object UsageItem | yes |  |
| `to` | string | yes |  |
| `totals` | object | yes |  |

### UserOut

UserOut fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `email` | string | yes |  |
| `email_verified` | boolean | yes |  |
| `id` | string | yes |  |
| `last_login_at` | string or null | yes |  |
| `name` | string or null | yes |  |

### ValidationError

ValidationError fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ctx` | object | no |  |
| `input` | any | no |  |
| `loc` | array of string or integer | yes |  |
| `msg` | string | yes |  |
| `type` | string | yes |  |

### Webhook

Webhook fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `description` | string or null | yes |  |
| `event_types` | array of string | yes |  |
| `id` | string | yes |  |
| `previous_secret_expires_at` | string or null | yes |  |
| `status` | string | yes |  |
| `updated_at` | string | yes |  |
| `url` | string | yes |  |

### WebhookCreate

WebhookCreate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string or null | no |  |
| `event_types` | array of string or null | no | Empty or omitted: every event type. |
| `url` | string | yes |  |

### WebhookList

WebhookList fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Webhook | yes |  |

### WebhookUpdate

WebhookUpdate fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string or null | no |  |
| `event_types` | array of string or null | no |  |
| `status` | string (active, paused) or null | no |  |
| `url` | string or null | no |  |

### WebhookWithSecret

WebhookWithSecret fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `description` | string or null | yes |  |
| `event_types` | array of string | yes |  |
| `id` | string | yes |  |
| `previous_secret_expires_at` | string or null | yes |  |
| `secret` | string | yes | whsec_... Shown once. Verify webhook-signature with it. |
| `status` | string | yes |  |
| `updated_at` | string | yes |  |
| `url` | string | yes |  |

### faxforagents__api__routes__inbox__InboxItem

faxforagents__api__routes__inbox__InboxItem fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | no |  |
| `document_id` | string or null | yes |  |
| `duration_secs` | integer or null | no |  |
| `environment` | string (live, test) | no |  |
| `expires_at` | string or null | no |  |
| `from` | string or null | no |  |
| `id` | string | yes |  |
| `media_status` | string | no |  |
| `note` | string or null | no |  |
| `number_id` | string or null | no |  |
| `pages` | integer | yes |  |
| `partial_content` | boolean | no |  |
| `project_id` | string or null | no |  |
| `provider` | string | no |  |
| `read_at` | string or null | no |  |
| `received_at` | string | yes |  |
| `status` | string | yes |  |
| `to` | string | yes |  |

### faxforagents__api__schemas__InboxItem

faxforagents__api__schemas__InboxItem fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | no |  |
| `document_id` | string or null | yes |  |
| `from` | string or null | no |  |
| `id` | string | yes |  |
| `note` | string or null | no |  |
| `pages` | integer | yes |  |
| `received_at` | string | yes |  |
| `status` | string | yes |  |
| `to` | string | yes |  |

### faxforagents__api__schemas__Me

faxforagents__api__schemas__Me fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actor` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `key_id` | string | yes |  |
| `key_prefix` | string | yes |  |
| `org_id` | string | yes |  |
| `project_id` | string | yes |  |
| `scopes` | array of string | yes |  |

### faxforagents__auth__schemas__Me

faxforagents__auth__schemas__Me fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `csrf_token` | string | yes |  |
| `organization` | object OrganizationSummary or null | yes |  |
| `organizations` | array of object OrganizationSummary | yes |  |
| `passkeys` | integer | yes |  |
| `providers` | object Providers | yes |  |
| `session` | object SessionInfo | yes |  |
| `user` | object UserOut | yes |  |