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

# API reference

> The base URL, the rate limit and its headers, the errors and the caching rules of the Faxbeep API.

The Faxbeep API is read-only JSON for the tests that faxbeep.com shows. For what you can do with it, see [Developers](/developers/overview).

## Base URL

| Item | Value |
| - | - |
| Base URL | `https://faxbeep.com` |
| Authentication | None: no account, no token, no API key |
| Method | `GET` only |
| Format | JSON, UTF-8. Times are ISO 8601 in UTC, with `Z` |
| Browsers | Allowed from any origin (CORS) |

## Endpoints

| Endpoint | Returns |
| - | - |
| `GET /api/faxes` | A JSON array of tests, newest first |
| `GET /api/faxes/{slug}` | One test, as a JSON object |

There is no `data` wrapper: the list is a bare array, and one test is a bare object.

| Parameter of the list | Default | Rule |
| - | - | - |
| `limit` | 20 | From 1 to 100. No offset and no paging |
| `since` | 24 hours ago | ISO 8601 with an offset. Only tests that arrived later |
| `from` | None | Only tests of this sender. The full value |

The pages [List faxes](/api-reference/faxes/list-faxes) and [Get a fax](/api-reference/faxes/get-a-fax) have each parameter and field in detail, and a playground to try them.

## Rate limit

60 requests each minute for one IPv4 address, or for one IPv6 /64 block. The two endpoints share one count. Each answer from an endpoint counts, also a 404, 410 or 422.

| Header | On | Meaning |
| - | - | - |
| `X-RateLimit-Limit` | Each answer | Requests allowed each minute |
| `X-RateLimit-Remaining` | Each answer | Requests left in this minute |
| `Retry-After` | 429 only | Seconds to wait before the next request |
| `X-RateLimit-Reset` | 429 only | When requests are allowed again, as Unix time |

When you get 429, wait the number of seconds in `Retry-After`. To wait for a new test, see [Test in CI](/developers/ci).

## Errors

Each error is JSON, also when your client sends no `Accept` header.

| Status | When | Body |
| - | - | - |
| 404 | No test has this slug yet, or the path is not an endpoint | `{"message": ""}` |
| 410 | The test was removed: after 30 days, or on a request | `{"message": ""}` |
| 422 | A parameter is not valid | `message`, and `errors` for each parameter |
| 429 | The rate limit is used up | `message` |

A 422 body names the parameter:

```json theme={null}
{
  "message": "The since field format is invalid.",
  "errors": {
    "since": ["The since field format is invalid."]
  }
}
```

The usual causes of a 422:

* `since` is a date alone (`2026-10-01`) or a time with no offset (`2026-10-01T14:25:00`). Add `Z`.
* `since` has a `+` offset that was not encoded. Send `+02:00` as `%2B02:00`, or use UTC with `Z`.
* `limit` is not a number from 1 to 100.
* `from` is longer than 255 characters, or is sent as an array (`from[]=...`).

A request with the default User-Agent of the Python `urllib` module is refused with 403, and the body is not JSON. Set your own User-Agent header. The Python examples on these pages do this.

## Caching

Each answer has `Cache-Control: no-store, private`, errors too. Do not cache an answer: a new test can appear at any time.

## What the API does not have

* No webhooks or notifications. Ask the API again until your test appears.
* No paging and no offset. One call gives 100 tests at most.
* No way to send a fax, to remove a test, or to set a private test. To remove a test, see [Remove a fax](/privacy/remove-a-fax).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.