{"openapi":"3.1.0","info":{"title":"Emboss","version":"1.1.0","description":"Emboss turns any PDF form into a fillable one, fills it from data or supporting documents, reads a filled form back, and faxes the result to a US, Canadian or Mexican fax number. Operations: make fillable, fill from values, fill from documents, read a filled form back, send by fax. Pay per operation over plain HTTP with x402 or MPP, no account needed. The account API, the MCP server and the A2A agent are described at the links in x-service-info.","x-guidance":"Emboss turns any PDF form into a fillable one, fills it from data or supporting documents, reads a filled form back, and faxes the result to a US, Canadian or Mexican fax number. Paid operations, each a POST with the PDF as JSON (pdf_url or pdf_base64) or as a multipart file field: POST /pay/make-fillable turns a flat PDF into a fillable one; POST /pay/fill fills a PDF from a JSON object of field values (`values`: an object in the JSON body, or a JSON string in the `values` form field); POST /pay/fill-with-context fills a PDF from supporting documents (`context_base64` or `context` files, `context_text`, or `context_urls`); POST /pay/read reads a filled PDF back into labelled values; POST /pay/fax faxes the PDF to a destination number (`to`, E.164 form such as +15025551212), priced per transmitted page, cards with a 0.50 USD minimum and stablecoins at the exact price. Send the request with no payment first: the server answers 402 with a WWW-Authenticate: Payment challenge (methods: tempo stablecoin USDC.e at the exact price, or stripe card via Shared Payment Tokens with a 0.50 USD minimum). Pay it, resend the identical request with the Authorization: Payment credential, and receive 202 with job_id, status_url, quote_id and status plus a Payment-Receipt header, within about 10 seconds. The 402 already carries job_id and status_url. Check status_url every few seconds until status is ready or failed, then download the result. For a fax, ready means the carrier accepted it; keep checking until result.status is delivered, failed or expired. A failed job runs again at no charge when you resend the same request with the same payment (with MPP, only while its payment challenge is valid), up to 3 runs in all. Prices scale with page count; the 402 challenge always carries the exact amount. Free: POST /pay/quote with the PDF returns the page count and the exact price of each operation before you pay. Capabilities: Turn a flat or scanned PDF form into a fillable PDF with detected fields; Fill a PDF form from structured data such as JSON or key-value answers; Fill a PDF form using facts found in supporting documents; Read the values out of a filled PDF form, labelled by field, with a completeness verdict when the form is known; Send a PDF to a fax number and track delivery, priced per transmitted page. Every 402 offers two ways to pay: MPP (Tempo USDC.e or a card, WWW-Authenticate: Payment) and x402 (USDC on Base, PAYMENT-REQUIRED header); pay either and resend the same request. The x402 accepts list also carries one gasless entry per Circle Gateway chain (extra.name GatewayWalletBatched); pay any entry.","contact":{"name":"Emboss","url":"https://getemboss.ai","email":"contact@getemboss.ai"},"x-agentic-access-contract":"https://api.getemboss.ai/agentic-access.json"},"servers":[{"url":"https://api.getemboss.ai"}],"externalDocs":{"url":"https://getemboss.ai/docs/pay-per-call/mpp","description":"Pay-per-call guide: the 402 handshake, both rails, and worked examples."},"paths":{"/pay/make-fillable":{"post":{"operationId":"pay_make_fillable","summary":"Turn a flat or scanned PDF form into a fillable PDF with detected fields.","description":"Turn a flat or scanned PDF form into a fillable PDF with detected fields. Also: detect form fields in a PDF; add fillable fields to a document; extract a PDF form schema; make a government or business form fillable; XFA forms; Adobe LiveCycle forms; Adobe dynamic forms. Input: a PDF file. Ephemeral processing: source and output documents are deleted 60 to 70 minutes after the last activity on a form.","tags":["forms"],"security":[],"parameters":[{"name":"dry_run","in":"query","required":false,"description":"Set to true to rehearse this call. Nothing is stored, charged or sent, and no AI is used. The answer says what the real call would do: whether it would succeed or be refused (with the exact status and error it would return), the price and the pages it is based on, and, on an account, whether the free monthly allowance covers it or a card is needed.","schema":{"type":"boolean","default":false},"example":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pdf_url":{"type":"string","format":"uri","description":"Public https URL of the PDF form; Emboss downloads it (25 MB limit)."},"pdf_base64":{"type":"string","contentEncoding":"base64","description":"The PDF form as standard base64 (25 MB decoded limit)."}},"oneOf":[{"required":["pdf_url"]},{"required":["pdf_base64"]}]},"example":{"pdf_url":"https://example.com/forms/building-permit.pdf"}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The PDF form."}},"required":["file"]},"example":{"file":"<the PDF form, sent as a file>"}}}},"responses":{"402":{"description":"Payment Required","content":{"application/problem+json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"The job this price is for."},"status_url":{"type":"string","format":"uri","description":"The job's free status link, token included: it answers awaiting_payment until you pay, then follows the job. Keep it: a lost answer to the paid call is recovered here."}}},"example":{"detail":"Payment required for this operation.","job_id":"eeeeeeee-ffff-0000-1111-222222222222","status":402,"status_url":"https://api.getemboss.ai/pay/jobs/eeeeeeee-ffff-0000-1111-222222222222?token=EXAMPLE","title":"Payment Required","type":"https://paymentauth.org/problems/payment-required"}}}},"202":{"description":"Paid and accepted, within about 10 seconds. status is ready when the job finished in that time, working when it is still running (check status_url every few seconds until status is ready or failed), or failed with the reason in error. The Payment-Receipt header carries the MPP receipt.","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"status_url":{"type":"string","format":"uri"},"quote_id":{"type":"string"},"status":{"type":"string","enum":["ready","working","failed"],"description":"The job's status when the paid call answered."},"poll_after_seconds":{"type":"integer","description":"On working: how long to wait before checking status_url."},"error":{"type":"string","description":"On failed: why, in plain words."},"retry":{"type":"string","description":"On failed, when a free run is available: how to run it again at no charge."},"artifact_id":{"type":"string","description":"The result artifact's id, when the op produced one."},"artifact_token":{"type":"string","description":"Bearer token for artifact_id (anonymous callers only)."},"artifacts":{"type":"array","items":{"type":"object"},"description":"Every artifact the op produced: [{artifact_id, role, mime_type}]."}},"required":["job_id","status_url","quote_id","status"]},"example":{"job_id":"eeeeeeee-ffff-0000-1111-222222222222","poll_after_seconds":3,"quote_id":"eeeeeeee-ffff-0000-1111-222222222222","status":"working","status_url":"https://api.getemboss.ai/pay/jobs/eeeeeeee-ffff-0000-1111-222222222222?token=EXAMPLE"}}}},"400":{"description":"Not a readable PDF, or a required input is missing."},"409":{"description":"Conflict: a different document or settings from the ones priced, a payment already used for another price, or a payment already being processed. This request is not charged."},"410":{"description":"Gone: the result has expired (its files are deleted about an hour after the job), so a resend runs nothing; a new run needs a new payment."},"413":{"description":"Too many pages or too much context."},"200":{"description":"A rehearsal (?dry_run=true): what the real call would do, with nothing stored, charged or sent and no AI used. outcome says whether it would succeed or be refused; a refusal carries the status and body the real call would answer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DryRunAnswer"},"example":{"dry_run":true,"operation":"create_form","outcome":"would_succeed","refusal":null,"price":{"cents":5,"pages":1,"covered_by_free_allowance":false,"free_left_this_month":null,"card_needed":false},"details":{"known_layout":false,"field_count":null},"not_checked":["Which boxes the form has and what each one is called are not checked; a dry run runs no field detection and uses no AI."]}}}}},"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","amount":"0.05","min":"0.05","max":"1.00"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50"}},{"mpp":{"method":"stripe","intent":"charge","currency":"usd"}},{"x402":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bda02913"}},{"x402":{"scheme":"exact","network":"eip155:1","asset":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:43114","asset":"0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:42161","asset":"0xaf88d065e77c8cc2239327c5edb3a432268e5831","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:10","asset":"0x0b2c639c533813f4aa9d7837caf62653d097ff85","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:137","asset":"0x3c499c542cef5e3811e1192ce70d8cc03d5c3359","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:130","asset":"0x078d782b760474a361dda0af3839290b0ef57ad6","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:146","asset":"0x29219dd400f2bf60e5a23d13be72b486d4038894","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:480","asset":"0x79a02482a880bce3f13e09da970dc34db4cd24d1","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:1329","asset":"0xe15fc38f6d8c56af07bbcbe3baf5708a2bf42392","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:999","asset":"0xb88339cb7199b77e23db6e890353e22632ba630f","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:5042","asset":"0x3600000000000000000000000000000000000000","facilitator":"circle-gateway"}}],"amount":"50000","unitType":"request","description":"Turn a flat or scanned PDF form into a fillable PDF with detected fields. Input: a PDF file.","priceNote":"Price scales with page count between min and max; the exact amount for your request is in the 402 challenge. Two cases sit outside the range: a two-call fill-with-context that also orders a submission package adds the package price, and a card payment is never less than 0.50 USD."},"x-agentic-access":{"action-class":"acting","consequence":"write","subject":"optional","audience":"https://api.getemboss.ai","x-authorization":"per-call-payment","audit":"required"}}},"/pay/fill-with-context":{"post":{"operationId":"pay_fill_with_context","summary":"Fill a PDF form using facts found in supporting documents.","description":"Fill a PDF form using facts found in supporting documents. Also: fill a PDF form from DOCX, spreadsheets, images, JSON, or other documents; pre-fill a government form from supporting paperwork; complete an application from a resume or company details; extract answers from context documents into a form. Input: a PDF file plus one or more context files and/or context_text/context_urls. Ephemeral processing: source and output documents are deleted 60 to 70 minutes after the last activity on a form.","tags":["forms"],"security":[],"parameters":[{"name":"dry_run","in":"query","required":false,"description":"Set to true to rehearse this call. Nothing is stored, charged or sent, and no AI is used. The answer says what the real call would do: whether it would succeed or be refused (with the exact status and error it would return), the price and the pages it is based on, and, on an account, whether the free monthly allowance covers it or a card is needed.","schema":{"type":"boolean","default":false},"example":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pdf_url":{"type":"string","format":"uri","description":"Public https URL of the PDF form; Emboss downloads it (25 MB limit)."},"pdf_base64":{"type":"string","contentEncoding":"base64","description":"The PDF form as standard base64 (25 MB decoded limit)."},"context_base64":{"type":"array","maxItems":5,"items":{"type":"object","required":["name","base64"],"properties":{"name":{"type":"string","description":"Filename, used to tell documents apart."},"base64":{"type":"string","contentEncoding":"base64","description":"The document as standard base64."}}},"description":"Up to 5 supporting documents (PDF, text, images) as base64."},"context_text":{"type":"string","maxLength":200000,"description":"Supporting text, up to 200,000 characters."},"context_urls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":5,"description":"Up to 5 public https URLs of supporting documents."},"policy":{"type":"string","enum":["safe","strict"],"description":"How sure Emboss must be before writing a value: safe (default) writes high and medium confidence, strict writes high only."},"mode":{"type":"string","enum":["one_call","two_call"],"description":"one_call (default) returns the finished PDF; two_call returns a proposal and a commit token so the caller can resolve open items before anything is written."},"package":{"type":"boolean","description":"mode=two_call only: also produce one submission package at commit, holding the filled form, the attachments uploaded against the proposal, and the receipt. Priced into this quote."}},"oneOf":[{"required":["pdf_url"]},{"required":["pdf_base64"]}]},"example":{"context_text":"Grace Hopper, born 9 December 1906, 1 Navy Way, Arlington, VA 22202.","pdf_url":"https://example.com/forms/building-permit.pdf","policy":"safe"}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The PDF form."},"context":{"type":"array","items":{"type":"string","format":"binary"},"description":"Supporting documents (PDF, text, images)."},"context_text":{"type":"string","maxLength":200000,"description":"Supporting text, up to 200,000 characters."},"context_urls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":5,"description":"Up to 5 public https URLs of supporting documents."},"policy":{"type":"string","enum":["safe","strict"],"description":"How sure Emboss must be before writing a value: safe (default) writes high and medium confidence, strict writes high only."},"mode":{"type":"string","enum":["one_call","two_call"],"description":"one_call (default) returns the finished PDF; two_call returns a proposal and a commit token so the caller can resolve open items before anything is written."},"package":{"type":"boolean","description":"mode=two_call only: also produce one submission package at commit, holding the filled form, the attachments uploaded against the proposal, and the receipt. Priced into this quote."}},"required":["file"]},"example":{"context":["<a supporting document, sent as a file>"],"file":"<the PDF form, sent as a file>","policy":"safe"}}}},"responses":{"402":{"description":"Payment Required","content":{"application/problem+json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"The job this price is for."},"status_url":{"type":"string","format":"uri","description":"The job's free status link, token included: it answers awaiting_payment until you pay, then follows the job. Keep it: a lost answer to the paid call is recovered here."}}},"example":{"detail":"Payment required for this operation.","job_id":"eeeeeeee-ffff-0000-1111-222222222222","status":402,"status_url":"https://api.getemboss.ai/pay/jobs/eeeeeeee-ffff-0000-1111-222222222222?token=EXAMPLE","title":"Payment Required","type":"https://paymentauth.org/problems/payment-required"}}}},"202":{"description":"Paid and accepted, within about 10 seconds. status is ready when the job finished in that time, working when it is still running (check status_url every few seconds until status is ready or failed), or failed with the reason in error. The Payment-Receipt header carries the MPP receipt. With mode=two_call, proposal_id, commit_token and proposal_url appear here only when the job finishes within the wait; otherwise they appear in the status check's answer once status is ready.","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"status_url":{"type":"string","format":"uri"},"quote_id":{"type":"string"},"status":{"type":"string","enum":["ready","working","failed"],"description":"The job's status when the paid call answered."},"poll_after_seconds":{"type":"integer","description":"On working: how long to wait before checking status_url."},"error":{"type":"string","description":"On failed: why, in plain words."},"retry":{"type":"string","description":"On failed, when a free run is available: how to run it again at no charge."},"artifact_id":{"type":"string","description":"The result artifact's id, when the op produced one."},"artifact_token":{"type":"string","description":"Bearer token for artifact_id (anonymous callers only)."},"artifacts":{"type":"array","items":{"type":"object"},"description":"Every artifact the op produced: [{artifact_id, role, mime_type}]."},"proposal_id":{"type":"string","description":"two_call only: the proposal to read and commit."},"commit_token":{"type":"string","description":"two_call only: send as X-Proposal-Token on the proposal routes; lives 45 minutes."},"proposal_url":{"type":"string","format":"uri","description":"two_call only: GET the proposal, token included."}},"required":["job_id","status_url","quote_id","status"]},"example":{"job_id":"eeeeeeee-ffff-0000-1111-222222222222","poll_after_seconds":3,"quote_id":"eeeeeeee-ffff-0000-1111-222222222222","status":"working","status_url":"https://api.getemboss.ai/pay/jobs/eeeeeeee-ffff-0000-1111-222222222222?token=EXAMPLE"}}}},"400":{"description":"Not a readable PDF, or a required input is missing."},"409":{"description":"Conflict: a different document or settings from the ones priced, a payment already used for another price, or a payment already being processed. This request is not charged."},"410":{"description":"Gone: the result has expired (its files are deleted about an hour after the job), so a resend runs nothing; a new run needs a new payment."},"413":{"description":"Too many pages or too much context."},"200":{"description":"A rehearsal (?dry_run=true): what the real call would do, with nothing stored, charged or sent and no AI used. outcome says whether it would succeed or be refused; a refusal carries the status and body the real call would answer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DryRunAnswer"},"example":{"dry_run":true,"operation":"fill_from_context","outcome":"would_succeed","refusal":null,"price":{"cents":8,"pages":2,"covered_by_free_allowance":false,"free_left_this_month":null,"card_needed":false},"details":{"form_pages":1,"document_pages":1,"combined_pages":2,"creates_form":true},"not_checked":["Whether the AI fills each box correctly is not checked; a dry run uses no AI."]}}}}},"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","amount":"0.08","min":"0.08","max":"12.93"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50"}},{"mpp":{"method":"stripe","intent":"charge","currency":"usd"}},{"x402":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bda02913"}},{"x402":{"scheme":"exact","network":"eip155:1","asset":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:43114","asset":"0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:42161","asset":"0xaf88d065e77c8cc2239327c5edb3a432268e5831","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:10","asset":"0x0b2c639c533813f4aa9d7837caf62653d097ff85","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:137","asset":"0x3c499c542cef5e3811e1192ce70d8cc03d5c3359","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:130","asset":"0x078d782b760474a361dda0af3839290b0ef57ad6","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:146","asset":"0x29219dd400f2bf60e5a23d13be72b486d4038894","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:480","asset":"0x79a02482a880bce3f13e09da970dc34db4cd24d1","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:1329","asset":"0xe15fc38f6d8c56af07bbcbe3baf5708a2bf42392","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:999","asset":"0xb88339cb7199b77e23db6e890353e22632ba630f","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:5042","asset":"0x3600000000000000000000000000000000000000","facilitator":"circle-gateway"}}],"amount":"80000","unitType":"request","description":"Fill a PDF form using facts found in supporting documents. Input: a PDF file plus one or more context files and/or context_text/context_urls.","priceNote":"Price scales with page count between min and max; the exact amount for your request is in the 402 challenge. Two cases sit outside the range: a two-call fill-with-context that also orders a submission package adds the package price, and a card payment is never less than 0.50 USD."},"x-agentic-access":{"action-class":"acting","consequence":"write","subject":"optional","audience":"https://api.getemboss.ai","x-authorization":"per-call-payment","audit":"required"}}},"/pay/fill":{"post":{"operationId":"pay_fill","summary":"Fill a PDF form from structured data such as JSON or key-value answers.","description":"Fill a PDF form from structured data such as JSON or key-value answers. Also: fill a PDF form from JSON; populate form fields from data; complete a PDF application from known values; write answers into a form. Input: a PDF file plus a values JSON object mapping field names to answers. Ephemeral processing: source and output documents are deleted 60 to 70 minutes after the last activity on a form.","tags":["forms"],"security":[],"parameters":[{"name":"dry_run","in":"query","required":false,"description":"Set to true to rehearse this call. Nothing is stored, charged or sent, and no AI is used. The answer says what the real call would do: whether it would succeed or be refused (with the exact status and error it would return), the price and the pages it is based on, and, on an account, whether the free monthly allowance covers it or a card is needed.","schema":{"type":"boolean","default":false},"example":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pdf_url":{"type":"string","format":"uri","description":"Public https URL of the PDF form; Emboss downloads it (25 MB limit)."},"pdf_base64":{"type":"string","contentEncoding":"base64","description":"The PDF form as standard base64 (25 MB decoded limit)."},"values":{"type":"object","additionalProperties":true,"description":"A JSON object mapping field names to answers."}},"oneOf":[{"required":["pdf_url"]},{"required":["pdf_base64"]}]},"example":{"pdf_url":"https://example.com/forms/building-permit.pdf","values":{"Email":"grace@example.com","Full Name":"Grace Hopper"}}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The PDF form."},"values":{"type":"string","description":"A JSON object (as a string) mapping field names to answers."}},"required":["file"]},"example":{"file":"<the PDF form, sent as a file>","values":"{\"Full Name\": \"Grace Hopper\", \"Email\": \"grace@example.com\"}"}}}},"responses":{"402":{"description":"Payment Required","content":{"application/problem+json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"The job this price is for."},"status_url":{"type":"string","format":"uri","description":"The job's free status link, token included: it answers awaiting_payment until you pay, then follows the job. Keep it: a lost answer to the paid call is recovered here."}}},"example":{"detail":"Payment required for this operation.","job_id":"eeeeeeee-ffff-0000-1111-222222222222","status":402,"status_url":"https://api.getemboss.ai/pay/jobs/eeeeeeee-ffff-0000-1111-222222222222?token=EXAMPLE","title":"Payment Required","type":"https://paymentauth.org/problems/payment-required"}}}},"202":{"description":"Paid and accepted, within about 10 seconds. status is ready when the job finished in that time, working when it is still running (check status_url every few seconds until status is ready or failed), or failed with the reason in error. The Payment-Receipt header carries the MPP receipt.","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"status_url":{"type":"string","format":"uri"},"quote_id":{"type":"string"},"status":{"type":"string","enum":["ready","working","failed"],"description":"The job's status when the paid call answered."},"poll_after_seconds":{"type":"integer","description":"On working: how long to wait before checking status_url."},"error":{"type":"string","description":"On failed: why, in plain words."},"retry":{"type":"string","description":"On failed, when a free run is available: how to run it again at no charge."},"artifact_id":{"type":"string","description":"The result artifact's id, when the op produced one."},"artifact_token":{"type":"string","description":"Bearer token for artifact_id (anonymous callers only)."},"artifacts":{"type":"array","items":{"type":"object"},"description":"Every artifact the op produced: [{artifact_id, role, mime_type}]."}},"required":["job_id","status_url","quote_id","status"]},"example":{"job_id":"eeeeeeee-ffff-0000-1111-222222222222","poll_after_seconds":3,"quote_id":"eeeeeeee-ffff-0000-1111-222222222222","status":"working","status_url":"https://api.getemboss.ai/pay/jobs/eeeeeeee-ffff-0000-1111-222222222222?token=EXAMPLE"}}}},"400":{"description":"Not a readable PDF, or a required input is missing."},"409":{"description":"Conflict: a different document or settings from the ones priced, a payment already used for another price, or a payment already being processed. This request is not charged."},"410":{"description":"Gone: the result has expired (its files are deleted about an hour after the job), so a resend runs nothing; a new run needs a new payment."},"413":{"description":"Too many pages or too much context."},"200":{"description":"A rehearsal (?dry_run=true): what the real call would do, with nothing stored, charged or sent and no AI used. outcome says whether it would succeed or be refused; a refusal carries the status and body the real call would answer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DryRunAnswer"},"example":{"dry_run":true,"operation":"fill","outcome":"would_succeed","refusal":null,"price":{"cents":7,"pages":1,"covered_by_free_allowance":false,"free_left_this_month":null,"card_needed":false},"details":{},"not_checked":["Which of your values land in which boxes cannot be checked until the form is made fillable; a dry run runs no field detection and uses no AI."]}}}}},"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","amount":"0.07","min":"0.07","max":"1.02"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50"}},{"mpp":{"method":"stripe","intent":"charge","currency":"usd"}},{"x402":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bda02913"}},{"x402":{"scheme":"exact","network":"eip155:1","asset":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:43114","asset":"0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:42161","asset":"0xaf88d065e77c8cc2239327c5edb3a432268e5831","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:10","asset":"0x0b2c639c533813f4aa9d7837caf62653d097ff85","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:137","asset":"0x3c499c542cef5e3811e1192ce70d8cc03d5c3359","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:130","asset":"0x078d782b760474a361dda0af3839290b0ef57ad6","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:146","asset":"0x29219dd400f2bf60e5a23d13be72b486d4038894","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:480","asset":"0x79a02482a880bce3f13e09da970dc34db4cd24d1","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:1329","asset":"0xe15fc38f6d8c56af07bbcbe3baf5708a2bf42392","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:999","asset":"0xb88339cb7199b77e23db6e890353e22632ba630f","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:5042","asset":"0x3600000000000000000000000000000000000000","facilitator":"circle-gateway"}}],"amount":"70000","unitType":"request","description":"Fill a PDF form from structured data such as JSON or key-value answers. Input: a PDF file plus a values JSON object mapping field names to answers.","priceNote":"Price scales with page count between min and max; the exact amount for your request is in the 402 challenge. Two cases sit outside the range: a two-call fill-with-context that also orders a submission package adds the package price, and a card payment is never less than 0.50 USD."},"x-agentic-access":{"action-class":"acting","consequence":"write","subject":"optional","audience":"https://api.getemboss.ai","x-authorization":"per-call-payment","audit":"required"}}},"/pay/read":{"post":{"operationId":"pay_read","summary":"Read the values out of a filled PDF form, labelled by field, with a completeness verdict when the form is known.","description":"Read the values out of a filled PDF form, labelled by field, with a completeness verdict when the form is known. Also: extract form data; get values from a filled PDF; read a completed form back into data; pull the answers out of a filled application; turn a filled PDF into JSON. Input: a filled PDF file. Ephemeral processing: source and output documents are deleted 60 to 70 minutes after the last activity on a form.","tags":["forms"],"security":[],"parameters":[{"name":"dry_run","in":"query","required":false,"description":"Set to true to rehearse this call. Nothing is stored, charged or sent, and no AI is used. The answer says what the real call would do: whether it would succeed or be refused (with the exact status and error it would return), the price and the pages it is based on, and, on an account, whether the free monthly allowance covers it or a card is needed.","schema":{"type":"boolean","default":false},"example":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pdf_url":{"type":"string","format":"uri","description":"Public https URL of the PDF form; Emboss downloads it (25 MB limit)."},"pdf_base64":{"type":"string","contentEncoding":"base64","description":"The PDF form as standard base64 (25 MB decoded limit)."}},"oneOf":[{"required":["pdf_url"]},{"required":["pdf_base64"]}]},"example":{"pdf_url":"https://example.com/filled/building-permit.pdf"}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The PDF form."}},"required":["file"]},"example":{"file":"<the filled PDF, sent as a file>"}}}},"responses":{"402":{"description":"Payment Required","content":{"application/problem+json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"The job this price is for."},"status_url":{"type":"string","format":"uri","description":"The job's free status link, token included: it answers awaiting_payment until you pay, then follows the job. Keep it: a lost answer to the paid call is recovered here."}}},"example":{"detail":"Payment required for this operation.","job_id":"eeeeeeee-ffff-0000-1111-222222222222","status":402,"status_url":"https://api.getemboss.ai/pay/jobs/eeeeeeee-ffff-0000-1111-222222222222?token=EXAMPLE","title":"Payment Required","type":"https://paymentauth.org/problems/payment-required"}}}},"202":{"description":"Paid and accepted, within about 10 seconds. status is ready when the job finished in that time, working when it is still running (check status_url every few seconds until status is ready or failed), or failed with the reason in error. The Payment-Receipt header carries the MPP receipt.","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"status_url":{"type":"string","format":"uri"},"quote_id":{"type":"string"},"status":{"type":"string","enum":["ready","working","failed"],"description":"The job's status when the paid call answered."},"poll_after_seconds":{"type":"integer","description":"On working: how long to wait before checking status_url."},"error":{"type":"string","description":"On failed: why, in plain words."},"retry":{"type":"string","description":"On failed, when a free run is available: how to run it again at no charge."},"artifact_id":{"type":"string","description":"The result artifact's id, when the op produced one."},"artifact_token":{"type":"string","description":"Bearer token for artifact_id (anonymous callers only)."},"artifacts":{"type":"array","items":{"type":"object"},"description":"Every artifact the op produced: [{artifact_id, role, mime_type}]."}},"required":["job_id","status_url","quote_id","status"]},"example":{"job_id":"eeeeeeee-ffff-0000-1111-222222222222","poll_after_seconds":3,"quote_id":"eeeeeeee-ffff-0000-1111-222222222222","status":"working","status_url":"https://api.getemboss.ai/pay/jobs/eeeeeeee-ffff-0000-1111-222222222222?token=EXAMPLE"}}}},"400":{"description":"Not a readable PDF, or a required input is missing."},"409":{"description":"Conflict: a different document or settings from the ones priced, a payment already used for another price, or a payment already being processed. This request is not charged."},"410":{"description":"Gone: the result has expired (its files are deleted about an hour after the job), so a resend runs nothing; a new run needs a new payment."},"413":{"description":"Too many pages or too much context."},"200":{"description":"A rehearsal (?dry_run=true): what the real call would do, with nothing stored, charged or sent and no AI used. outcome says whether it would succeed or be refused; a refusal carries the status and body the real call would answer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DryRunAnswer"},"example":{"dry_run":true,"operation":"read_form","outcome":"would_succeed","refusal":null,"price":{"cents":1,"pages":1,"covered_by_free_allowance":false,"free_left_this_month":null,"card_needed":false},"details":{"pages":1},"not_checked":[]}}}}},"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","amount":"0.01","min":"0.01","max":"0.01"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50"}},{"mpp":{"method":"stripe","intent":"charge","currency":"usd"}},{"x402":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bda02913"}},{"x402":{"scheme":"exact","network":"eip155:1","asset":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:43114","asset":"0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:42161","asset":"0xaf88d065e77c8cc2239327c5edb3a432268e5831","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:10","asset":"0x0b2c639c533813f4aa9d7837caf62653d097ff85","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:137","asset":"0x3c499c542cef5e3811e1192ce70d8cc03d5c3359","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:130","asset":"0x078d782b760474a361dda0af3839290b0ef57ad6","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:146","asset":"0x29219dd400f2bf60e5a23d13be72b486d4038894","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:480","asset":"0x79a02482a880bce3f13e09da970dc34db4cd24d1","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:1329","asset":"0xe15fc38f6d8c56af07bbcbe3baf5708a2bf42392","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:999","asset":"0xb88339cb7199b77e23db6e890353e22632ba630f","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:5042","asset":"0x3600000000000000000000000000000000000000","facilitator":"circle-gateway"}}],"amount":"10000","unitType":"request","description":"Read the values out of a filled PDF form, labelled by field, with a completeness verdict when the form is known. Input: a filled PDF file.","priceNote":"Price scales with page count between min and max; the exact amount for your request is in the 402 challenge. Two cases sit outside the range: a two-call fill-with-context that also orders a submission package adds the package price, and a card payment is never less than 0.50 USD."},"x-agentic-access":{"action-class":"acting","consequence":"write","subject":"optional","audience":"https://api.getemboss.ai","x-authorization":"per-call-payment","audit":"required"}}},"/pay/fax":{"post":{"operationId":"pay_fax","summary":"Send a PDF to a fax number and track delivery, priced per transmitted page.","description":"Send a PDF to a fax number and track delivery, priced per transmitted page. Also: fax a PDF; send a document by fax; fax this form to an agency; transmit a PDF to a fax line; outbound fax from an agent. Input: a PDF file and a destination fax number in E.164 form. Card payments have a 0.50 minimum, stablecoins pay the exact price. Ephemeral processing: source and output documents are deleted 60 to 70 minutes after the last activity on a form. For a fax, ready means the carrier accepted it; keep checking until result.status is delivered, failed or expired. A busy, unanswered or dropped call is retried automatically up to three more times over about 17 minutes before the fax is written off. A failed or expired fax is refunded: by card automatically, up to three refunds a day, and by stablecoin through contact@getemboss.ai.","tags":["forms"],"security":[],"parameters":[{"name":"dry_run","in":"query","required":false,"description":"Set to true to rehearse this call. Nothing is stored, charged or sent, and no AI is used. The answer says what the real call would do: whether it would succeed or be refused (with the exact status and error it would return), the price and the pages it is based on, and, on an account, whether the free monthly allowance covers it or a card is needed.","schema":{"type":"boolean","default":false},"example":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pdf_url":{"type":"string","format":"uri","description":"Public https URL of the PDF to fax; Emboss downloads it (10 MB limit)."},"pdf_base64":{"type":"string","contentEncoding":"base64","description":"The PDF to fax as standard base64 (10 MB decoded limit)."},"to":{"type":"string","description":"Destination fax number in E.164 form, e.g. +15025551212."},"artifact_id":{"type":"string","description":"JSON body only: the id of a previously registered artifact to fax, in place of a fresh PDF. Exactly one of the multipart file, pdf_url, pdf_base64, or artifact_id is required."},"artifact_token":{"type":"string","description":"JSON body only: the bearer token for artifact_id, required when the artifact has no owner account."},"sources":{"type":"array","maxItems":20,"description":"JSON body only: a list of prior artifacts, faxed together as one packet, in place of a fresh PDF. Exactly one of the multipart file, pdf_url, pdf_base64, artifact_id, or sources is required.","items":{"type":"object","properties":{"artifact_id":{"type":"string","description":"A prior artifact's id."},"artifact_token":{"type":"string","description":"The bearer token for an anonymous artifact_id."},"pages":{"type":"string","description":"An optional page range, such as 1-3,7."}},"required":["artifact_id"]}}},"oneOf":[{"required":["pdf_url"]},{"required":["pdf_base64"]},{"required":["artifact_id"]},{"required":["sources"]}]},"example":{"pdf_url":"https://example.com/filled/building-permit.pdf","to":"+15025550123"}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The PDF form."},"to":{"type":"string","description":"Destination fax number in E.164 form, e.g. +15025551212."}},"required":["file"]},"example":{"file":"<the PDF to fax, sent as a file>","to":"+15025550123"}}}},"responses":{"402":{"description":"Payment Required","content":{"application/problem+json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"The job this price is for."},"status_url":{"type":"string","format":"uri","description":"The job's free status link, token included: it answers awaiting_payment until you pay, then follows the job. Keep it: a lost answer to the paid call is recovered here."}}},"example":{"detail":"Payment required for this operation.","job_id":"eeeeeeee-ffff-0000-1111-222222222222","status":402,"status_url":"https://api.getemboss.ai/pay/jobs/eeeeeeee-ffff-0000-1111-222222222222?token=EXAMPLE","title":"Payment Required","type":"https://paymentauth.org/problems/payment-required"}}}},"202":{"description":"Paid and accepted, within about 10 seconds. status is ready when the job finished in that time, working when it is still running (check status_url every few seconds until status is ready or failed), or failed with the reason in error. The Payment-Receipt header carries the MPP receipt.","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"status_url":{"type":"string","format":"uri"},"quote_id":{"type":"string"},"status":{"type":"string","enum":["ready","working","failed"],"description":"The job's status when the paid call answered."},"poll_after_seconds":{"type":"integer","description":"On working: how long to wait before checking status_url."},"error":{"type":"string","description":"On failed: why, in plain words."},"retry":{"type":"string","description":"On failed, when a free run is available: how to run it again at no charge."},"artifact_id":{"type":"string","description":"The result artifact's id, when the op produced one."},"artifact_token":{"type":"string","description":"Bearer token for artifact_id (anonymous callers only)."},"artifacts":{"type":"array","items":{"type":"object"},"description":"Every artifact the op produced: [{artifact_id, role, mime_type}]."}},"required":["job_id","status_url","quote_id","status"]},"example":{"job_id":"eeeeeeee-ffff-0000-1111-222222222222","poll_after_seconds":3,"quote_id":"eeeeeeee-ffff-0000-1111-222222222222","status":"working","status_url":"https://api.getemboss.ai/pay/jobs/eeeeeeee-ffff-0000-1111-222222222222?token=EXAMPLE"}}}},"400":{"description":"Not a readable PDF, or a required input is missing."},"409":{"description":"Conflict: a different document or settings from the ones priced, a payment already used for another price, or a payment already being processed. This request is not charged."},"410":{"description":"Gone: the result has expired (its files are deleted about an hour after the job), so a resend runs nothing; a new run needs a new payment."},"413":{"description":"Too many pages or too much context."},"200":{"description":"A rehearsal (?dry_run=true): what the real call would do, with nothing stored, charged or sent and no AI used. outcome says whether it would succeed or be refused; a refusal carries the status and body the real call would answer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DryRunAnswer"},"example":{"dry_run":true,"operation":"send_fax","outcome":"would_succeed","refusal":null,"price":{"cents":3,"pages":1,"covered_by_free_allowance":false,"free_left_this_month":null,"card_needed":false},"details":{"to_e164":"+15025550123","country":"United States or Canada","pages":1},"not_checked":["Whether the other end answers and receives the fax is not checked; a dry run sends nothing and dials no one."]}}}}},"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","amount":"0.03","min":"0.03","max":"3.00"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50"}},{"mpp":{"method":"stripe","intent":"charge","currency":"usd"}},{"x402":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bda02913"}},{"x402":{"scheme":"exact","network":"eip155:1","asset":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:43114","asset":"0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:42161","asset":"0xaf88d065e77c8cc2239327c5edb3a432268e5831","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:10","asset":"0x0b2c639c533813f4aa9d7837caf62653d097ff85","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:137","asset":"0x3c499c542cef5e3811e1192ce70d8cc03d5c3359","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:130","asset":"0x078d782b760474a361dda0af3839290b0ef57ad6","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:146","asset":"0x29219dd400f2bf60e5a23d13be72b486d4038894","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:480","asset":"0x79a02482a880bce3f13e09da970dc34db4cd24d1","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:1329","asset":"0xe15fc38f6d8c56af07bbcbe3baf5708a2bf42392","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:999","asset":"0xb88339cb7199b77e23db6e890353e22632ba630f","facilitator":"circle-gateway"}},{"x402":{"scheme":"exact","network":"eip155:5042","asset":"0x3600000000000000000000000000000000000000","facilitator":"circle-gateway"}}],"amount":"30000","unitType":"request","description":"Send a PDF to a fax number and track delivery, priced per transmitted page. Input: a PDF file and a destination fax number in E.164 form. Card payments have a 0.50 minimum, stablecoins pay the exact price.","priceNote":"Price scales with page count between min and max; the exact amount for your request is in the 402 challenge. Two cases sit outside the range: a two-call fill-with-context that also orders a submission package adds the package price, and a card payment is never less than 0.50 USD."},"x-agentic-access":{"action-class":"acting","consequence":"write","subject":"optional","audience":"https://api.getemboss.ai","x-authorization":"per-call-payment","escalation":{"human-in-the-loop":"conditional","triggers":["abnormal"]},"x-abnormal":"more than 10 faxes from one account within an hour","x-curation-reason":"Sends the document to someone else's fax machine. A new fax number alone needs no approval; a burst does.","audit":"required"}}},"/pay/quote":{"post":{"operationId":"pay_quote","summary":"Free price check for a PDF","description":"Free and stateless: returns the page count, whether the PDF already has form fields, and the exact price of every operation for this PDF. Call it before paying.","tags":["forms"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pdf_url":{"type":"string","format":"uri","description":"Public https URL of the PDF form; Emboss downloads it (25 MB limit)."},"pdf_base64":{"type":"string","contentEncoding":"base64","description":"The PDF form as standard base64 (25 MB decoded limit)."},"context_base64":{"type":"array","maxItems":5,"items":{"type":"object","required":["name","base64"],"properties":{"name":{"type":"string","description":"Filename, used to tell documents apart."},"base64":{"type":"string","contentEncoding":"base64","description":"The document as standard base64."}}},"description":"Up to 5 supporting documents (PDF, text, images) as base64."},"context_text":{"type":"string","maxLength":200000,"description":"Supporting text, up to 200,000 characters."},"context_urls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":5,"description":"Up to 5 public https URLs of supporting documents."},"policy":{"type":"string","enum":["safe","strict"],"description":"How sure Emboss must be before writing a value: safe (default) writes high and medium confidence, strict writes high only."},"mode":{"type":"string","enum":["one_call","two_call"],"description":"one_call (default) returns the finished PDF; two_call returns a proposal and a commit token so the caller can resolve open items before anything is written."}},"oneOf":[{"required":["pdf_url"]},{"required":["pdf_base64"]}]},"example":{"context_text":"Grace Hopper, born 9 December 1906, 1 Navy Way, Arlington, VA 22202.","pdf_url":"https://example.com/forms/building-permit.pdf"}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The PDF form."},"context":{"type":"array","items":{"type":"string","format":"binary"},"description":"Supporting documents (PDF, text, images)."},"context_text":{"type":"string","maxLength":200000,"description":"Supporting text, up to 200,000 characters."},"context_urls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":5,"description":"Up to 5 public https URLs of supporting documents."},"policy":{"type":"string","enum":["safe","strict"],"description":"How sure Emboss must be before writing a value: safe (default) writes high and medium confidence, strict writes high only."},"mode":{"type":"string","enum":["one_call","two_call"],"description":"one_call (default) returns the finished PDF; two_call returns a proposal and a commit token so the caller can resolve open items before anything is written."}},"required":["file"]},"example":{"context_text":"Grace Hopper, born 9 December 1906, 1 Navy Way, Arlington, VA 22202.","file":"<the PDF form, sent as a file>"}}}},"responses":{"200":{"description":"Free price check for this PDF.","content":{"application/json":{"schema":{"type":"object","properties":{"pages":{"type":"integer"},"already_fillable":{"type":"boolean"},"context_pages":{"type":"integer"},"prices":{"type":"object","additionalProperties":{"type":"object","description":"One job's line: its price, or, when the real call would refuse these documents, the refusal instead of a price.","properties":{"cents":{"type":"integer"},"usd":{"type":"string"},"atomic":{"type":"string"},"refusal":{"type":"object","description":"Present instead of a price when the job would be refused for this PDF: the status and body the real call answers, before any payment.","properties":{"status":{"type":"integer"},"body":{"type":"object"}}}}}},"methods":{"type":"array","items":{"type":"string"}},"card_minimum_usd":{"type":"string"},"next":{"type":"string"}},"required":["pages","already_fillable","context_pages","prices","methods","card_minimum_usd","next"]},"example":{"already_fillable":false,"card_minimum_usd":"0.50","context_pages":1,"expires":null,"methods":["tempo","stripe","x402"],"next":"POST /pay/<op> with the same file. The 402 challenge carries this exact price.","pages":1,"prices":{"fax":{"atomic":"30000","cents":3,"usd":"0.03"},"fill":{"atomic":"70000","cents":7,"usd":"0.07"},"fill-with-context":{"atomic":"80000","cents":8,"usd":"0.08"},"make-fillable":{"atomic":"50000","cents":5,"usd":"0.05"},"read":{"refusal":{"status":400,"body":{"detail":"no form boxes found; scanned or flattened forms are not read yet","status":400,"title":"Bad Request","type":"https://paymentauth.org/problems/bad-request"}}}}}}}},"400":{"description":"Not a readable PDF, or a required input is missing."},"413":{"description":"Too many pages or too much context."},"429":{"description":"Too many quote requests from this client."}},"x-agentic-access":{"action-class":"connected","consequence":"read","subject":"optional","audience":"https://api.getemboss.ai","audit":"none"}}},"/pay/jobs/{job_id}":{"get":{"operationId":"pay_job_status","summary":"Check on a paid job, free","description":"Free. The 402 and the 202 both carry this link as status_url, token included. Check status_url every few seconds until status is ready or failed. One plain word: awaiting_payment (priced, not yet paid), working (still running; check again after poll_after_seconds), ready (finished: result carries the output and, for a job that produces a file, a download link that stays the same on every check), failed (error says why; retry, when present, says how to run it again at no charge), or expired (the result's files are deleted, about an hour after the job, or a price that was never paid has expired: send the request again for a new one). For a fax, ready means the carrier accepted it; keep checking until result.status is delivered, failed or expired. A busy, unanswered or dropped call is retried automatically up to three more times over about 17 minutes before the fax is written off. A failed or expired fax is refunded: by card automatically, up to three refunds a day, and by stablecoin through contact@getemboss.ai. A resend with the same MPP payment, a free retry included, works only while its payment challenge stays valid, 15 minutes from the 402; after that, check status_url from the 402, and for a failed job contact contact@getemboss.ai with your job id.","tags":["forms"],"security":[],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"},"description":"The job_id from the 402 or the 202."},{"name":"token","in":"query","required":true,"schema":{"type":"string"},"description":"The token in status_url."}],"responses":{"200":{"description":"The job's status.","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"quote_id":{"type":"string"},"status":{"type":"string","enum":["awaiting_payment","working","ready","failed","expired"],"description":"One plain word: awaiting_payment (priced, not yet paid), working (still running; check again after poll_after_seconds), ready (finished: result carries the output and, for a job that produces a file, a download link that stays the same on every check), failed (error says why; retry, when present, says how to run it again at no charge), or expired (the result's files are deleted, about an hour after the job, or a price that was never paid has expired: send the request again for a new one). For a fax, ready means the carrier accepted it; keep checking until result.status is delivered, failed or expired. A busy, unanswered or dropped call is retried automatically up to three more times over about 17 minutes before the fax is written off. A failed or expired fax is refunded: by card automatically, up to three refunds a day, and by stablecoin through contact@getemboss.ai."},"quote_status":{"type":"string","description":"The quote's own older word: quoted, claimed, executed or expired."},"runs":{"type":"integer","description":"Runs used; one payment covers 3."},"result":{"type":"object","description":"On ready: the output, with download_url when the job produced a file (a read or a fax has none)."},"error":{"type":"string","description":"On failed or expired: why, in plain words."},"retry":{"type":"string","description":"On failed, when a free run is available: how to run it again at no charge."},"poll_after_seconds":{"type":"integer","description":"On working and awaiting_payment only: how long to wait before checking again."},"proposal_id":{"type":"string","description":"two_call only: the proposal to read and commit."},"commit_token":{"type":"string","description":"two_call only: send as X-Proposal-Token on the proposal routes; lives 45 minutes."},"proposal_url":{"type":"string","format":"uri","description":"two_call only: GET the proposal, token included."}},"required":["job_id","quote_id","status","quote_status","runs"]},"example":{"job_id":"eeeeeeee-ffff-0000-1111-222222222222","quote_id":"eeeeeeee-ffff-0000-1111-222222222222","quote_status":"executed","result":{"artifact_id":"99999999-aaaa-bbbb-cccc-dddddddddddd","download_url":"https://getemboss.ai/d/EXAMPLE","files":[{"content_type":"application/pdf","name":"building-permit-filled.pdf","url":"https://getemboss.ai/d/EXAMPLE"}]},"runs":1,"status":"ready"}}}},"403":{"description":"The token is missing or wrong."},"404":{"description":"No such job, or its quote was removed: an hour after it was made if it was never paid, 24 hours after it was made if it was."}},"x-agentic-access":{"action-class":"connected","consequence":"read","subject":"optional","audience":"https://api.getemboss.ai","audit":"none"}}}},"components":{"schemas":{"DryRunAnswer":{"type":"object","description":"The answer to a rehearsal (dry_run=true): what the real call would do, with nothing done. outcome is would_succeed or would_refuse; a refusal carries the exact status and body the real call would answer. price is what the real call would charge now (null for a delete); not_checked lists what a rehearsal cannot check.","properties":{"dry_run":{"type":"boolean","description":"Always true: this was a rehearsal."},"operation":{"type":"string","enum":["create_form","fill_from_context","prepare","fill","fill_batch","suggest_mapping","commit","verify","read_form","send_fax","delete_form","delete_attachment","execute_quote"],"description":"The operation rehearsed. execute_quote appears only when the call was refused before its quote could be read."},"outcome":{"type":"string","enum":["would_succeed","would_refuse"]},"refusal":{"type":["object","null"],"description":"null when the call would succeed.","properties":{"status":{"type":"integer","description":"The status the real call would answer."},"body":{"type":"object","description":"The body the real call would answer."}}},"price":{"type":["object","null"],"description":"What the real call would charge now; null for a delete. cents is null when it would be charged but the amount was not given.","properties":{"cents":{"type":["integer","null"]},"pages":{"type":"integer","description":"The pages the price is based on."},"covered_by_free_allowance":{"type":"boolean"},"free_left_this_month":{"type":["integer","null"],"description":"null where no free allowance applies."},"card_needed":{"type":"boolean"}}},"details":{"type":"object","description":"Facts the checks read, such as page counts."},"not_checked":{"type":"array","items":{"type":"string"},"description":"What a rehearsal cannot check, in plain words."}},"required":["dry_run","operation","outcome","refusal","price","details","not_checked"]}}},"x-service-info":{"realm":"api.getemboss.ai","docs":"https://getemboss.ai/docs/pay-per-call/mpp","llmsTxt":"https://api.getemboss.ai/pay/llms.txt","pricing":"https://getemboss.ai/pricing","accountApi":"https://api.getemboss.ai/internal/openapi.json","accountApiDocs":"https://api.getemboss.ai/docs","mcp":"https://api.getemboss.ai/.well-known/mcp.json","a2a":"https://api.getemboss.ai/.well-known/agent-card.json","ard":"https://api.getemboss.ai/.well-known/ard.json","aiCatalog":"https://api.getemboss.ai/.well-known/ai-catalog.json","llmsTxtRoot":"https://api.getemboss.ai/llms.txt","signup":"https://getemboss.ai/signup"}}