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"
}
}
}
}
}
}