docs
View as Markdown

Pay per call

Agents and scripts can pay Emboss per operation over plain HTTP, with no account and no API key. Send a request to the pay-per-call API, receive a payment challenge, pay it, and resend the same request with the payment credential. Emboss then runs the operation and returns a job you can poll.

Ephemeral processing: source and output documents are deleted 60 to 70 minutes after the last activity on a form. The pay-per-call API always runs under ephemeral processing.

A price that is never paid expires an hour after the request, and the documents sent with it are deleted at the next cleanup, within ten minutes after that.

The pay-per-call API lives at https://api.getemboss.ai/pay. It exposes five operations: make a flat PDF fillable, fill a PDF from context documents, fill a PDF from data, read a filled PDF back, and send a PDF by fax. Each is priced per call, starting at a few cents for a short form; longer forms cost more, and the exact price for your request is always in the payment challenge. See Pricing for the full schedule.

Limits and how documents are priced

Each request takes one PDF form of up to 10 MB and 100 pages, and up to 5 supporting documents, each up to 10 MB, with 30 MB for the whole request. Supporting documents count toward the price in page-equivalents: a PDF by its pages, an image as at least one page, and text, spreadsheets, Word files and JSON at about 1,750 characters per page. A request with more than 500 page-equivalents of documents is refused with 413.

Payment rails

  • Machine Payments Protocol (MPP): pay with USDC stablecoin on Tempo or with a credit card. Works with the standard MPP clients, including the tempo CLI and mppx.
  • x402: pay with USDC on Base, over the A2A endpoint or directly on the pay-per-call API, or gaslessly on every chain Circle Gateway supports. Works with the x402 SDKs for Python and JavaScript and with Circle's CLI.

If you already have an Emboss account, the regular API with an API key bills to your account instead and includes the free tier.

Getting the result

The payment challenge already carries the job's job_id and status_url, so you hold the link to the result before you pay. After you pay, check status_url until status is ready or failed; the answer says how long to wait between checks. The status is one of five words: awaiting_payment, working, ready, failed or expired (the result's files are deleted about an hour after the job, under ephemeral processing). For a fax, ready means the carrier accepted it; keep checking until result.status is delivered, failed or expired.

A fill from context documents whose supporting document is the blank form itself is refused with 422 and code document_same_as_form before any price is offered. A PDF whose form fields are built in a way that could compromise the service is refused the same way, with 422 and code pdf_unsafe, before any price is offered, so nothing is paid. The message is "Emboss does not process PDF files that could compromise the service." A fill that finds nothing in its documents still ends ready, and its result carries no_values_found in warnings and a message saying why. That payment stands: the documents were read and held no answers. If our side fails while reading the documents, the job ends failed instead, so the free re-run below applies.

Resending the identical paid request with the same payment never charges twice: it returns the job, runs a failed job again at no charge, up to three runs in all for one payment, and answers 410 Gone once the result has expired. With MPP this holds only while its payment challenge is valid; after that a resend gets a new price, so check status_url instead, and for a job that failed, write to contact@getemboss.ai with the job id. See Checking on a job.

Results carry an artifact_id

Every finished operation's result carries an artifact_id for the file it produced, and a pay-per-call result also carries an artifact_token next to it. Send both to a later paid operation, such as /pay/fax, to reuse that file without paying to upload it again; the token proves ownership in place of an account. /pay/fax also takes a sources list to fax several artifacts as one packet. See Artifacts and lineage.

Pay-per-call callers may also run the free utilities on artifacts they hold tokens for, over A2A or POST /utilities/{skill}, with the artifact_token on every source: no quote, no charge. See Free PDF utilities.

Discovery

  • Ops index: https://api.getemboss.ai/pay
  • OpenAPI manifest with per-operation payment info: https://api.getemboss.ai/openapi.json
  • Machine-readable summary: https://api.getemboss.ai/pay/llms.txt
  • Pricing as JSON: https://api.getemboss.ai/pay/pricing
  • OpenAPI for the pay-per-call API: https://api.getemboss.ai/pay/openapi.json
  • Free price check: https://api.getemboss.ai/pay/quote (POST the PDF; returns page count and the exact price per operation)
  • Listed in ARD registries: Neuronto indexes the Agentic Resource Discovery manifest at https://getemboss.ai/.well-known/ard.json, which other ARD registries can read too.

Each catalogue entry carries a signed trust manifest naming did:web:getemboss.ai, so a registry can verify the entry came from Emboss and is unchanged. See Trust and verification.

Every pay-per-job request runs under ephemeral processing: see how documents are handled and when they're deleted and the subprocessors that touch the request.