API documentation

Get started with the Edwyna API.

Edwyna is a JSON API for individual and transactional faxing. Prepare and validate a PDF first; charge and send it only after reviewing the returned destination and price.

Current status

Edwyna’s production REST API and remote MCP server are available for individual and transactional faxes. MCP clients connect through OAuth; REST clients use a narrowly scoped API key.

Compatible AI clients

Connect directly with MCP.

In an MCP-compatible client, add https://edwyna.com/mcp as a remote Streamable HTTP server. The client discovers Edwyna’s sign-in and permissions flow automatically. Sign in to an existing verified Edwyna account—or create and verify one—then approve the requested permissions. You do not copy an Edwyna API key into the AI client.

The client can then discover seven focused tools for checking price and balance, preparing a PDF, sending only after authorization, checking delivery, listing recent faxes, and optionally retrieving the transmitted PDF. Preparing and sending remain separate operations: prepare_fax does not charge or send; send_fax deducts $4 and communicates externally.

MCP resources: server metadata · authorization discovery

REST API quick start

Five requests to delivery, plus an optional download.

Create an account, verify its email, add prepaid credit, and create an API key. Production keys begin with edwyna_live_; test keys cannot authenticate to production. Grant only the scopes the software needs. Store the secret in a secret manager or protected environment variable named EDWYNA_API_KEY; never put it in a prompt, PDF, URL, or source file.

Check the balance

Requires balance:read.

curl -sS \
  -H "Authorization: Bearer ${EDWYNA_API_KEY}" \
  https://edwyna.com/v1/balance

Prepare and quote

Requires fax:prepare and enough available Edwyna credit to cover the quote (currently at least $4). The request waits for isolated validation: success returns a ready fax, while rejection returns an error without creating a fax. It does not charge or send, and there is no validation-status polling step. Preparation attempts and active drafts are rate-limited.

curl -sS \
  -H "Authorization: Bearer ${EDWYNA_API_KEY}" \
  -F destination_country=US \
  -F recipient_name="Recipient name" \
  -F recipient_fax="503-555-1212" \
  -F sender_name="Sender name" \
  -F sender_email="sender@example.com" \
  -F sender_phone="503-555-0100" \
  -F client_reference="your-reference" \
  -F document=@/path/to/document.pdf \
  https://edwyna.com/v1/fax-drafts

Review the response

Present the normalized fax number, page count, SHA-256 fingerprint, and exact price to the person authorizing the fax. Retain the returned fax_id. Quotes expire after 30 minutes.

{
  "fax_id": "FAX_ID",
  "status": "ready",
  "financial_status": "not_charged",
  "recipient": {"fax": "+15035551212", "country": "US"},
  "document": {"pages": 1, "sha256": "..."},
  "quote": {"price": {"amount_cents": 400, "display": "$4.00"}}
}

Authorize, charge, and queue

Requires fax:send. This is the consequential request: it deducts $4 and queues an external fax. Use a new idempotency key of 16–255 characters for this intended fax.

curl -sS -X POST \
  -H "Authorization: Bearer ${EDWYNA_API_KEY}" \
  -H "Idempotency-Key: YOUR_UNIQUE_SEND_KEY" \
  https://edwyna.com/v1/fax-drafts/FAX_ID/send

Check the final status

Requires fax:read. Poll responsibly until the status is delivered or failed. Delivery commonly takes 5–10 minutes and can take up to 45 minutes.

curl -sS \
  -H "Authorization: Bearer ${EDWYNA_API_KEY}" \
  https://edwyna.com/v1/faxes/FAX_ID

Optional: Download the transmitted PDF

This optional download is available after the status is delivered. It requires fax:read and returns the fax backend’s PDF representation of the pages Edwyna submitted. It is not proof of exactly what the receiving machine printed.

curl -sS \
  -H "Authorization: Bearer ${EDWYNA_API_KEY}" \
  --output edwyna-transmitted-FAX_ID.pdf \
  https://edwyna.com/v1/faxes/FAX_ID/transmitted-document

Instructions for AI agents

Safe tool behavior is part of the contract.

Never guess or infer a missing fax number, recipient identity, or document.
Treat draft creation as reversible preparation. Treat the send endpoint as a payment and external communication.
Before sending, show the normalized destination, PDF page count and fingerprint, and $4 price; obtain the user’s approval.
Use a fresh idempotency key for each intended fax. A network retry must reuse the same key for the same fax.
Retain the fax_id and check status. Never describe ready, queued, submitted, or transmitting as delivered.
Do not use Edwyna for bulk faxing, marketing, number discovery, or fax-list campaigns.
On an eligible final failure, report that Edwyna credit was restored; do not claim the original card was refunded.

Machine-readable resources: OpenAPI 3.1 contract · concise agent instructions · MCP server metadata

Reference

Available endpoints

Method	Path	Scope	Effect
`GET`	`/v1/pricing?destination_country=US`	Any active key	Returns authoritative price and page limit.
`GET`	`/v1/balance`	`balance:read`	Returns available prepaid credit.
`POST`	`/v1/fax-drafts`	`fax:prepare`	Requires sufficient available credit, validates one PDF, and creates a 30-minute quote.
`POST`	`/v1/fax-drafts/{fax_id}/send`	`fax:send`	Deducts $4 and queues one fax exactly once.
`GET`	`/v1/faxes/{fax_id}`	`fax:read`	Returns current delivery and financial status.
`GET`	`/v1/faxes/{fax_id}/transmitted-document`	`fax:read`	Optionally downloads the transmitted PDF after delivery.
`GET`	`/v1/faxes?status=delivered&limit=25`	`fax:read`	Lists the account’s recent faxes.

Errors and retries

Errors are JSON and include a request ID.

401Authentication

Missing, invalid, expired, or revoked API key.

402Balance

Insufficient prepaid credit.

403Authority

Missing scope, suspended account, or configured key limit.

409Conflict

Fax state, expired quote, or idempotency conflict.

422Validation

Unsupported destination, invalid fields, or rejected PDF.

429Limits

Daily fax or spending limit reached.

{
  "error": {
    "code": "insufficient_balance",
    "message": "The prepaid balance is insufficient.",
    "request_id": "...",
    "details": []
  }
}

Ready to begin?

Create an account and a narrowly scoped key.

Create account