API documentation

For developers and AI agents. The API speaks the REST shapes below (base /api/v1); in this POC the same operations run as the product's API actions, authenticated with the same keys. The rules don't change for bots: ciphertext only, no document storage, minimal audit log.

Hosting & data practices

DocFlow's public service is hosted on Cloudflare (free plan), a global edge network — not EU-pinned hosting, and DocFlow makes no EU-only storage or data-residency claim: on the free plan, data placement is automatic and requests are served from the edge nearest the caller. Data practices are GDPR-aligned as a standard of practice, not a server location: data minimisation (account details + a minimal audit log — who signed, when, SHA-256 — kept 12 months, then deleted), no document storage (ciphertext only, purged 7 days after delivery), end-to-end encryption throughout, and Cloudflare acting as a processor under its data processing terms (processor DPA). The same practices cover API and MCP traffic, and DocFlow serves customers in the EU and the US.

Bot signup — POST /api/v1/signup (no human needed)

Bots create their own account: POST /api/v1/signup with { email, agent_name } — no auth, no web form. Response 201: { api_key (a df_test_ key, shown once), key_prefix, plan: { tier: 'bot_free', test_per_day: 50, live_per_month: 10, max_signers: 5, max_doc_bytes: 10485760, key_rate_per_min: 60 }, dns_verification: { host: '_docflow-verify.<your domain>', record_type: 'TXT', value: 'docflow-verify=<token>' }, next_steps }. The account is flagged as a bot account and is API-only (no usable web password). Guards: max 3 signups per source IP per day (429 RATE_LIMITED past that); known disposable email domains are rejected (422 DISPOSABLE_EMAIL); one account per email. The df_test_ key works immediately in the full test flow. Caps are APPLIED: 50 test processes/day per account, documents up to 10 MB measured on the ciphertext; test data purges 7 days after delivery like everything else.

Verify & go live — bot verification and live keys

A bot account can only create a df_live_ key after automatic identity verification — ONE of: (a) EMAIL CODE: POST /api/v1/bot/verify-email/request with your key (Bearer) generates a 6-digit code (SHA-256 stored, 30-min validity); confirm it at POST /api/v1/bot/verify-email/confirm { code }. POC honesty: with no mail gateway connected, the code is returned in the request response as poc_code — the same pattern as signer OTP codes; in production it is emailed and never returned. (b) DNS PROOF: publish the TXT record from the signup response at _docflow-verify.<email domain>, then POST /api/v1/bot/verify-dns/check with your key (GET /api/v1/bot/verify-dns re-reads the record to publish). Once verified, create the live key with any existing key: POST /api/v1/keys { label, environment: 'live' } → { key (shown once), prefix }. Before verification, that call fails with 422 VERIFICATION_REQUIRED. Live caps on bot_free: 10 live documents/month, max 5 signers per document, 10 MB documents, 60 requests/minute per key. The owner may raise an account to bot_paid by hand (200 live documents/month, 25 signers) — plan structure only, no checkout in the POC. SUSPENSION: the owner can suspend a bot account; while suspended, ALL its keys are rejected on REST and MCP with 403 SUSPENDED, until reactivated.

Authentication

Send your key in the Authorization header: `Authorization: Bearer df_live_...` — or `Authorization: Bearer df_test_...` for the test environment. Human accounts create and revoke keys in Settings → API; bot accounts sign up via POST /api/v1/signup and create further keys via POST /api/v1/keys (live keys require verification — see 'Verify & go live'). Keys are shown once, stored only as hashes, and rate-limited per key: 120 requests/minute for human accounts, 60/minute for bot accounts. A key only ever sees processes in its own environment: test keys see and create test processes (badged 'TEST' in the web UI, wipeable in one click in Settings); live keys see and create live ones. A revoked key stops working immediately, and a suspended account's keys are all rejected (403 SUSPENDED).

Usage metering (what we record about your calls)

Every key-authenticated call — REST and MCP alike — is metered with metadata only: the owning account, the key's id and label, its environment (live/test), the timestamp, the endpoint or tool name, the outcome status and an approximate duration. Document content, ciphertext and payloads are never recorded — the same minimal-log philosophy as the audit trail. You can see your own usage in Settings → API usage (totals for today / 7 days / 30 days with a live-vs-test split, per-endpoint and per-tool breakdown, per-key totals, and your recent calls); the platform owner sees a platform-wide panel across accounts — including bot accounts with their plan tier, caps, current-period usage, verification and suspension state. Retention: daily totals are kept; the detailed event list keeps only the newest 200 events per account and nothing older than 30 days. Metering never blocks a call by itself; the applied limits are the per-key rate limit (120/min human accounts, 60/min bot accounts) and the bot plan caps (see 'Bot signup' and 'Verify & go live').

The encryption contract (read this first)

DocFlow's server never receives plaintext or keys. Your bot must: (1) generate an AES-256-GCM key; (2) encrypt the document payload (JSON: {kind:'pdf'|'image',fileName,dataB64,mime} for an uploaded file, or {kind:'docx',fileName,html} for a DOCX your client converted to HTML — the signed PDF is generated from that rendering); (3) send only ciphertext + IV; (4) build each signer's link as {app}/#/sign/{token}?k={base64url-key} and deliver it to the signer yourself. Signing, final-PDF assembly and delivery all happen in browsers holding the key. If your bot loses the key, the document is unrecoverable — by design.

Fillable fields (inside the encrypted payload)

The payload JSON may carry a fields array — definitions live inside the ciphertext, never on the server. Each field: { id, type, assignee, required, label, page, x, y, w, h, options?, default_value?, read_only?, show_if? }. type ∈ signature | initials | full_name | date | sign_date | text | title | company | address | email | checkbox | dropdown | radio | number. options is the choice list for dropdown/radio. default_value pre-fills the field (still editable unless read_only is true, in which case the signer only reads it). show_if: { field_id, equals } hides the field unless that other field's value equals the given one — evaluated in the signer's browser. assignee is a signer position (0-based) or -1 for the sender, whose values go in the payload's sender_values map {fieldId: value}. page is 0-based (PDF uploads); x/y/w/h are fractions (0–1) of that page (for image uploads, of the image). Each signer fills their visible fields before signing — a required field left empty, or an email/date/number value failing its format check, blocks the signature — and their values come back to you as ciphertext: field_values_cipher_text / field_values_cipher_iv on each signer in GET /api/v1/processes/{id}, decryptable with your key. Values are rendered into the delivered PDF at the marked positions. The audit log records only that fields were completed, never values.

Create a signing process from an uploaded document — POST /api/v1/processes

Body: { title, source_type: 'upload', file_name?, cipher_text, cipher_iv, signers: [...], signing_mode?, expires_at?, language?, message? }. YOU define the signers array: 1–25 participants (the POC cap) — add as many as the document needs. Each participant is { name, email } or { name, phone } — an email or a phone number in international format (+12145550123); exactly one contact per participant — plus optional role ('signer' default | 'approver' approves without signing | 'copy' only receives the final document; at least one signer is required), access_mode ('none' default | 'code' with access_code — only its SHA-256 hash is stored | 'otp' — one-time 6-digit code, email participants only) and private_message (a note only that participant sees). signing_mode: 'sequential' (default — array order, one at a time) or 'parallel' (any order). expires_at: ISO deadline after which links stop working and the process is marked expired. language: 'en'|'pt'|'es' signing-page language. message: a general note shown to every participant. Response 201: { process: {id, status:'sent', ...}, links: [{contact, contact_type, role, token, position}] }. Combine each token with your key to form signing links. Phone participants: the link is returned for you to deliver (e.g. by your own SMS) — DocFlow does not send SMS in the POC.

Get status / download — GET /api/v1/processes/{id}

Response: the process object with status (sent | in_progress | completed | delivered | cancelled | declined | expired | purged), per-participant states, roles and timestamps, document_sha256 and content_fingerprint after delivery, and — while inside the 7-day window — final_cipher_text/final_cipher_iv so your bot can decrypt the signed PDF with the key it holds. After purge_after, ciphertext fields are null forever.

List processes — GET /api/v1/processes

Metadata only (no ciphertext): id, title, status, environment, signer states, timestamps, document hash. Newest first, up to 100. Only processes in the key's own environment are listed.

Cancel a process — POST /api/v1/processes/{id}/cancel

Cancels an in-flight process and wipes its ciphertext immediately. Delivered processes cannot be cancelled. Response: { ok: true }.

Remind a participant — POST /api/v1/processes/{id}/remind

Body: { position }. Records a reminder for the participant at that position (they must not have finished). The reminder is written to the audit trail and fires the process.reminder webhook; delivery stays with you — re-send the participant's signing link (the POC has no mail/SMS gateway). DocFlow also records an automatic reminder when the participant whose turn it is has not opened or signed after 3 days. Response: { ok: true, reminder_count }.

Replace a participant — POST /api/v1/processes/{id}/replace-signer

Body: { position, name, email | phone, role? }. Replaces a participant who has not signed/approved yet: same position in the order, a fresh signing link (the new token is in the response), the old link stops working, and the replacement is written to the audit trail. Response: { replaced: true, signing_link: { position, name, contact, contact_type, role, token } }.

Webhooks

Configure one HTTPS endpoint per account in Settings → API. Events: process.sent, process.opened, process.signed, process.approved, process.completed, process.delivered, process.purged, process.cancelled, process.declined, process.expired, process.reminder. Payloads contain metadata + the document SHA-256 only — never content. Each delivery is signed: X-DocFlow-Signature: sha256=HMAC_SHA256(secret, raw body). Verify it before trusting an event.

Feature requests — POST /api/v1/feature-requests

Missing a capability? Don't give up — tell us. Body: { trying_to_do, missing_capability, use_case, requester_label?, contact?, channel: 'api' }. Works with an API key (30/min) or anonymously (5/min, honeypot-protected). Governance: requests are proposals; the owner personally reviews and approves every feature. Submission does not guarantee implementation, and requests conflicting with DocFlow's principles are declined by design. Never send document content.

Errors & limits

Errors return { error: { code, message } }: 401 UNAUTHORIZED (bad/revoked key), 403 SUSPENDED (the account is suspended by the owner — all its keys are rejected until reactivation), 404 NOT_FOUND, 422 VALIDATION (including DISPOSABLE_EMAIL at signup and VERIFICATION_REQUIRED when an unverified bot account asks for a live key), 429 RATE_LIMITED (per key: 120/min human accounts, 60/min bot accounts; feature requests 30/min keyed, 5/min anonymous; bot signup 3/IP/day) and 429 QUOTA_EXCEEDED (a bot plan cap was hit: 50 test processes/day, 10 live documents/month on bot_free, max signers per document, or the 10 MB document cap — the message names the cap and when it resets; never a silent failure). POC plan limits: free during the POC. Human accounts: up to 25 signers per process, no monthly document cap. Bot accounts (plan tier bot_free): caps above; bot_paid (owner-assigned, no checkout in the POC): 200 live documents/month, 25 signers. Signers always free.

Automate with your bot in 5 minutes

1) Sign up by API: POST /api/v1/signup { email, agent_name } → you get a df_test_ key immediately (no human, no web form). 2) Rehearse in the test environment: generate an AES-GCM key, encrypt your document payload, POST /api/v1/processes with your signers in order (test caps: 50/day, 10 MB). 3) Verify your identity (email code or DNS TXT proof) and create a df_live_ key via POST /api/v1/keys. 4) Send each signer their link (token + your key in the fragment). 5) Subscribe to webhooks, or poll GET /api/v1/processes/{id}; on 'delivered', decrypt final_cipher_text with your key to get the signed PDF — within 7 days, before the purge.

MCP server — the same capabilities as agent tools

Prefer tools over raw HTTP? Connect your agent to DocFlow's remote MCP server (Streamable HTTP, JSON-RPC 2.0) at https://getdocflow.eu/mcp with the SAME API key: header 'Authorization: Bearer df_live_...' (or df_test_ for the test environment). Tools: docflow_create_process, docflow_get_process, docflow_list_processes, docflow_download_signed_pdf, docflow_get_audit_trail, docflow_cancel_process, docflow_remind_signer, docflow_replace_signer, docflow_request_feature. The encryption contract is identical — tools move ciphertext only, your agent keeps the key, and nothing about a document is ever logged. Full catalog, connection snippets and the server.json registry manifest: see the MCP server page (#/mcp).

openapi.json

→ serves at https://getdocflow.eu/openapi.json
{
  "openapi": "3.1.0",
  "info": {
    "title": "DocFlow API",
    "version": "1.0.0-poc",
    "description": "DocFlow is an upload-and-sign service with end-to-end encrypted e-signature. The API is ciphertext-only: bots hold the AES-256-GCM key, the server can never read documents. Documents are purged 7 days after delivery; the minimal audit log (who signed, when, SHA-256) is kept 12 months. Hosted on Cloudflare (global network — not EU-pinned hosting, no EU-only storage claim); GDPR-aligned practices: data minimisation, no document storage, minimal 12-month audit log, processors under data processing terms. Feature requests are proposals reviewed and approved personally by the owner — never auto-implemented.",
    "contact": {
      "name": "DocFlow",
      "url": "https://getdocflow.eu"
    },
    "license": {
      "name": "POC — beta, provided as-is"
    }
  },
  "servers": [
    {
      "url": "https://getdocflow.eu/api/v1",
      "description": "DocFlow POC"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from Settings → API: df_live_... for live processes, df_test_... for the test environment (a key only sees its own environment)."
      }
    },
    "schemas": {
      "Process": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "proc_9f2c41ab77e0d"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "sent",
              "in_progress",
              "completed",
              "delivered",
              "cancelled",
              "declined",
              "expired",
              "purged"
            ]
          },
          "signing_mode": {
            "type": "string",
            "enum": [
              "sequential",
              "parallel"
            ]
          },
          "environment": {
            "type": "string",
            "enum": [
              "live",
              "test"
            ]
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "language": {
            "type": "string",
            "enum": [
              "en",
              "pt",
              "es"
            ]
          },
          "document_sha256": {
            "type": [
              "string",
              "null"
            ]
          },
          "content_fingerprint": {
            "type": [
              "string",
              "null"
            ],
            "description": "SHA-256 of the signed pages, printed inside the delivered PDF's verification page"
          },
          "signers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "email": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Signer email, when registered by email"
                },
                "phone": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Signer phone (international format), when registered by phone"
                },
                "contact_type": {
                  "type": "string",
                  "enum": [
                    "email",
                    "phone"
                  ]
                },
                "contact": {
                  "type": "string",
                  "description": "The contact used for this signer (email or phone)"
                },
                "role": {
                  "type": "string",
                  "enum": [
                    "signer",
                    "approver",
                    "copy"
                  ]
                },
                "order": {
                  "type": "integer"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "waiting",
                    "sent",
                    "opened",
                    "signed",
                    "approved",
                    "declined"
                  ]
                },
                "signed_at": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                },
                "field_values_cipher_text": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Ciphertext of this signer's fillable-field values (AES-GCM, your key); null until they sign"
                }
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "delivered_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "purge_after": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/processes": {
      "post": {
        "summary": "Create a document and start a signing process",
        "description": "Send AES-GCM ciphertext only — encrypt in your client with a key you keep. Sequential mode (default): participants act in array order, one at a time. Parallel mode: everyone can act in any order.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title",
                  "source_type",
                  "cipher_text",
                  "cipher_iv",
                  "signers"
                ],
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "source_type": {
                    "type": "string",
                    "enum": [
                      "upload"
                    ]
                  },
                  "file_name": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "cipher_text": {
                    "type": "string",
                    "description": "Base64 AES-256-GCM ciphertext of the document payload JSON"
                  },
                  "cipher_iv": {
                    "type": "string",
                    "description": "Base64 GCM IV"
                  },
                  "signing_mode": {
                    "type": "string",
                    "enum": [
                      "sequential",
                      "parallel"
                    ],
                    "description": "Default sequential"
                  },
                  "expires_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time",
                    "description": "Deadline; links stop working after it"
                  },
                  "language": {
                    "type": "string",
                    "enum": [
                      "en",
                      "pt",
                      "es"
                    ],
                    "description": "Signing-page language"
                  },
                  "message": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "General note shown to every participant"
                  },
                  "signers": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 25,
                    "description": "You choose how many participants (1–25 in the POC). Each takes a name plus exactly one contact: an email or a phone in international format. At least one must have role 'signer'.",
                    "items": {
                      "type": "object",
                      "required": [
                        "name"
                      ],
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string",
                          "format": "email"
                        },
                        "phone": {
                          "type": "string",
                          "description": "International format, e.g. +12145550123"
                        },
                        "role": {
                          "type": "string",
                          "enum": [
                            "signer",
                            "approver",
                            "copy"
                          ],
                          "description": "signer (default) signs; approver approves without signing; copy only receives the final document"
                        },
                        "access_mode": {
                          "type": "string",
                          "enum": [
                            "none",
                            "code",
                            "otp"
                          ],
                          "description": "code requires access_code (stored only as SHA-256); otp is a one-time 6-digit code, email participants only"
                        },
                        "access_code": {
                          "type": "string",
                          "description": "Required when access_mode is 'code'"
                        },
                        "private_message": {
                          "type": "string",
                          "description": "Note shown only to this participant"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Process created and sent; returns per-signer link tokens",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked API key"
          },
          "403": {
            "description": "SUSPENDED — the account is suspended by the owner; all its keys are rejected until reactivation"
          },
          "429": {
            "description": "Rate limit (per key: 120/min human accounts, 60/min bot accounts) or QUOTA_EXCEEDED — a bot plan cap was hit (50 test processes/day, 10 live documents/month on bot_free, max signers per document, 10 MB document cap); the message names the cap and when it resets"
          }
        }
      },
      "get": {
        "summary": "List processes (metadata only)",
        "responses": {
          "200": {
            "description": "Array of Process objects without ciphertext"
          }
        }
      }
    },
    "/processes/{id}": {
      "get": {
        "summary": "Get process status and, before purge, the encrypted final PDF",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Process object; final_cipher_text present only while delivered and inside the 7-day window"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/processes/{id}/cancel": {
      "post": {
        "summary": "Cancel an in-flight process (wipes ciphertext immediately)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{ ok: true }"
          },
          "409": {
            "description": "Delivered processes cannot be cancelled"
          }
        }
      }
    },
    "/processes/{id}/remind": {
      "post": {
        "summary": "Record a reminder for a participant who hasn't acted",
        "description": "The reminder lands in the audit trail and fires the process.reminder webhook; re-send the participant's link yourself (the POC has no mail/SMS gateway). An automatic reminder is also recorded after 3 days without opening/signing.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "position"
                ],
                "properties": {
                  "position": {
                    "type": "integer",
                    "description": "0-based participant position"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ ok: true, reminder_count }"
          },
          "409": {
            "description": "Participant already finished or process closed"
          }
        }
      }
    },
    "/processes/{id}/replace-signer": {
      "post": {
        "summary": "Replace a participant who hasn't acted yet (fresh link, same position)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "position",
                  "name"
                ],
                "properties": {
                  "position": {
                    "type": "integer",
                    "description": "0-based participant position"
                  },
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "phone": {
                    "type": "string",
                    "description": "International format"
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "signer",
                      "approver",
                      "copy"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ replaced: true, signing_link: { token, ... } } — the old link stops working"
          },
          "409": {
            "description": "Participant already signed/approved or process closed"
          }
        }
      }
    },
    "/signup": {
      "post": {
        "summary": "Bot self-service signup — create a bot account + df_test_ key (no human, no web form)",
        "description": "A bot sends an email + agent name and immediately receives a bot account (flagged as a bot account, plan tier bot_free) and a df_test_ API key that works in the full test flow. Guards: max 3 signups per source IP per day; known disposable email domains rejected (422 DISPOSABLE_EMAIL); one account per email. The account is API-only (no usable web password). Live keys unlock only after identity verification (email code or DNS TXT proof). Caps are applied, not just measured: 50 test processes/day, documents up to 10 MB.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "agent_name"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "The bot account's email — verification for the live tier happens through this address or its domain."
                  },
                  "agent_name": {
                    "type": "string",
                    "description": "The agent/product name shown in the owner's panel."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Account created. Returns the df_test_ key (shown once), the plan caps, and the DNS TXT record for domain verification",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "email": {
                      "type": "string"
                    },
                    "agent_name": {
                      "type": "string"
                    },
                    "api_key": {
                      "type": "string",
                      "description": "df_test_... — shown once, stored only as a hash"
                    },
                    "key_prefix": {
                      "type": "string"
                    },
                    "plan": {
                      "type": "object",
                      "properties": {
                        "tier": {
                          "type": "string",
                          "example": "bot_free"
                        },
                        "test_per_day": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "example": 50
                        },
                        "live_per_month": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "example": 10
                        },
                        "max_signers": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "example": 5
                        },
                        "max_doc_bytes": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "example": 10485760
                        },
                        "key_rate_per_min": {
                          "type": "integer",
                          "example": 60
                        }
                      }
                    },
                    "dns_verification": {
                      "type": "object",
                      "properties": {
                        "host": {
                          "type": "string",
                          "example": "_docflow-verify.example.com"
                        },
                        "record_type": {
                          "type": "string",
                          "example": "TXT"
                        },
                        "value": {
                          "type": "string",
                          "example": "docflow-verify=dfverify_..."
                        }
                      }
                    },
                    "next_steps": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation — including DISPOSABLE_EMAIL for known disposable domains, or an email that already has an account"
          },
          "429": {
            "description": "RATE_LIMITED — more than 3 signups from this source IP today"
          }
        }
      }
    },
    "/keys": {
      "post": {
        "summary": "Create another API key for your own account (bot door: how a verified bot gets its df_live_ key)",
        "description": "Authenticated with any existing key of the account. environment 'test' is always allowed; environment 'live' requires a VERIFIED bot account (email code or DNS proof) — before verification it fails with 422 VERIFICATION_REQUIRED. Human accounts are unrestricted.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "label",
                  "environment"
                ],
                "properties": {
                  "label": {
                    "type": "string"
                  },
                  "environment": {
                    "type": "string",
                    "enum": [
                      "live",
                      "test"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "{ key (shown once), prefix, environment }"
          },
          "401": {
            "description": "Invalid or revoked API key"
          },
          "403": {
            "description": "SUSPENDED — the account is suspended; all its keys are rejected"
          },
          "422": {
            "description": "VERIFICATION_REQUIRED — bot account not verified yet"
          }
        }
      }
    },
    "/bot/verify-email/request": {
      "post": {
        "summary": "Start email verification for your bot account (6-digit code)",
        "description": "Generates a 6-digit verification code for the key's bot account (only its SHA-256 is stored; 30-minute validity). POC: with no mail gateway connected, the code is returned in the response as poc_code — the same pattern as signer OTP codes; in production it is emailed to the account address and never returned.",
        "responses": {
          "200": {
            "description": "{ ok: true, already_verified, poc_code }"
          },
          "401": {
            "description": "Invalid or revoked API key"
          },
          "403": {
            "description": "SUSPENDED — the account is suspended"
          }
        }
      }
    },
    "/bot/verify-email/confirm": {
      "post": {
        "summary": "Confirm the email verification code — unlocks live keys",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "description": "The 6-digit code"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ ok: true, verified: true, method: 'email' }"
          },
          "401": {
            "description": "Invalid or revoked API key"
          },
          "422": {
            "description": "Code missing, expired or not matching"
          }
        }
      }
    },
    "/bot/verify-dns": {
      "get": {
        "summary": "Read the DNS TXT record your bot account must publish (domain proof)",
        "responses": {
          "200": {
            "description": "{ host: '_docflow-verify.<domain>', record_type: 'TXT', value: 'docflow-verify=<token>', verified }"
          },
          "401": {
            "description": "Invalid or revoked API key"
          }
        }
      }
    },
    "/bot/verify-dns/check": {
      "post": {
        "summary": "Check the DNS TXT proof — on a match the account is verified (method 'dns')",
        "responses": {
          "200": {
            "description": "{ ok: true, verified, records_seen }"
          },
          "401": {
            "description": "Invalid or revoked API key"
          },
          "403": {
            "description": "SUSPENDED — the account is suspended"
          }
        }
      }
    },
    "/feature-requests": {
      "post": {
        "summary": "Tell DocFlow what capability you are missing",
        "description": "For bots and humans. Auth optional (API key raises the rate limit). Requests are PROPOSALS: the owner personally reviews and approves every feature; submission does not guarantee implementation. Never include document content.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "trying_to_do",
                  "missing_capability",
                  "use_case"
                ],
                "properties": {
                  "trying_to_do": {
                    "type": "string"
                  },
                  "missing_capability": {
                    "type": "string"
                  },
                  "use_case": {
                    "type": "string"
                  },
                  "requester_label": {
                    "type": "string",
                    "description": "Your agent/product name"
                  },
                  "contact": {
                    "type": "string",
                    "description": "Optional contact email"
                  },
                  "channel": {
                    "type": "string",
                    "enum": [
                      "api"
                    ],
                    "description": "Bots calling this endpoint send 'api' so the owner's inbox can tell agent demand from human form submissions"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Request recorded in the owner's inbox"
          },
          "429": {
            "description": "Rate limit: 30/min with key, 5/min anonymous"
          }
        }
      }
    }
  }
}