Send content. Get a file.

1. Create a request

Generate a secret random Idempotency-Key of 32–128 URL-safe characters. Keep it for retries and downloads. Send Content-Type: application/json.

POST https://agentdocuments.online/api/v1/documents
Idempotency-Key: <random secret key>
Content-Type: application/json

{
  "format": "docx",
  "title": "Quarterly update",
  "filename": "quarterly-update",
  "content": {
    "markdown": "# Results\n\nRevenue grew **12%**.\n\n| Region | Status |\n| --- | --- |\n| 東京 | Ready |\n| München | Ready |"
  }
}

2. Authorize the quoted payment

The first response is HTTP 402 with an x402 v2 requirement in PAYMENT-REQUIRED and JSON accepts. Use an x402 client to sign the exact USDC amount on eip155:8453. Retry the identical request with PAYMENT-SIGNATURE. CDP verifies and settles the payment to the receiving wallet. The PAYMENT-RESPONSE response header contains the settlement receipt.

Price = max(0.01 USDC minimum, 3 × estimated variable cost), rounded up to micro-USDC. Format and complexity select a conservative cost profile; provider invoice costs are reconciled separately. See current format/tier prices or /api/v1/formats. Always use the returned quote. No later surcharge. Local demo uses demo:<Idempotency-Key>; hosted deployments never accept demo payments.

3. Download your document

{
  "request_id": "<uuid>",
  "status": "completed",
  "format": "docx",
  "filename": "quarterly-update.docx",
  "download_url": "https://agentdocuments.online/api/v1/documents/<uuid>/download",
  "file_size": 12345,
  "created_at": "<ISO timestamp>",
  "expires_at": "<ISO timestamp>",
  "validation": { "valid": true }
}

GET /api/v1/documents/<uuid>/download
Authorization: Bearer <original Idempotency-Key>

Use the same Bearer header with GET /api/v1/documents/{id} for metadata. Download URLs are not public: they require your key. Never put the key in a URL. Retention is 24 hours; save files before expiry.

Input formats

For DOCX/PDF, content accepts a plain string, {markdown: string} or {blocks: [...]}. Supported blocks: paragraph, heading (levels 1–3), list, table and page_break. Text can be a string or runs with text, bold, italic and href. DOCX preserves rich runs; PDF currently renders rich runs as plain text.

{
  "format": "xlsx",
  "title": "Results",
  "sheets": [
    {
      "name": "Results",
      "columns": [
        "Name",
        "Amount",
        "Date"
      ],
      "rows": [
        [
          "東京",
          10.5,
          {
            "date": "2026-09-28"
          }
        ],
        [
          "München",
          25,
          {
            "date": "2026-09-29"
          }
        ]
      ]
    }
  ]
}

XLSX accepts up to 10 sheets, 100 columns per sheet, 2,000 data rows per sheet and 10,000 cells total including headings. Cells accept text, finite numbers, booleans, null or {date: "YYYY-MM-DD"}. Text resembling a formula remains literal text. Intentional formulas use {formula: "SUM(B2:B5)"} (no leading =); external references, DDE, INDIRECT and network/macro functions are rejected. Macros are never accepted. Sheet names must be unique, valid Excel names, at most 31 characters.

Document tables support up to 12 columns and 500 rows. Every row must match its columns. PDF rows must fit on a page; split tall rows or use DOCX. Markdown supports headings, paragraphs, basic lists, tables, quotes and code as text; nested lists, images and HTML are rejected. Links permit HTTP, HTTPS and mailto. No external content is fetched.

Options: template is standard or compact; page_size is A4 or LETTER. Metadata accepts author, subject and language. No content is translated; language metadata never chooses geography. Unicode is preserved. PDF embeds Noto Sans and Noto Sans CJK; unsupported glyphs are rejected before payment. DOCX/XLSX rely on viewer fonts. Complex script shaping and bidirectional layout are not certified.

Limits, errors and retries

Maximum request 256 KiB, 100,000 text characters, 1,000 blocks, 4 MiB output. Default rate limit: 30 requests per minute per deployment-provided IP, including retrievals. HTML, scripts, uploads and code execution are unsupported.

• 400: invalid_json, invalid_input, invalid_key, unsupported_content or invalid_content.
• 402: payment_required or invalid_payment. Sign only the quoted requirement.
• 404: not_found, including unauthorized access.
• 409: idempotency_conflict or payment_replay. Retrieve the original request.
• 410: expired. The file is no longer accessible.
• 413: request_too_large, content_too_large or output_too_large.
• 415: unsupported_media_type or unsupported_encoding.
• 422: unsupported_glyph or failed generation. No settlement is submitted on generation failure.
• 429: rate_limited. Honor Retry-After.
• 503: not_configured, service_unavailable, payment_provider_unavailable or file_unavailable.

HTTP 202 reports processing, settling or settlement_unknown. Poll using your original key. Do not create a new payment. An operator can reconcile a confirmed blockchain payment to the already stored file. If a request dies before settlement, the operator can mark it uncharged after verifying no settlement was started.

Reuse the original key and identical content after network errors. Do not recycle keys across documents. Financial replay records are retained for 30 days after expiry; signed payment authorizations expire within minutes.

Discovery and health

/api/v1/formats returns formats, current prices, limits and retention. /api/v1/health checks configuration and database readiness; it does not certify a live payment or blockchain availability.