AI agents

Reference page for AI coding agents integrating mintfax

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

Read this first

Three artifacts let you understand mintfax without parsing prose.

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

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

Critical contracts

The minimum you need to make a correct first request.

Authentication

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

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

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

Idempotency

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

Full contract at idempotency.md.

Errors

Every error response carries this envelope:

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

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

Full catalog at errors.md.

Sandbox

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

Magic number catalog at sandbox.md.

Always do

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

Never do

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

Verify

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

curl -X POST https://api.mintfax.com/v1/faxes \
  -H "Authorization: Bearer mfx_test_..." \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -F "to=[phone]" \
  -F "file=@document.pdf"

Expected response (HTTP 201):

{
  "id": "fax_...",
  "status": "queued",
  "to": "[phone]",
  "created_at": "2026-01-15T10:30:00Z"
}

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

What to fetch next

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