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.

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 and 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.

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:

{
  "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.