{"openapi":"3.1.0","info":{"title":"Askhook API","version":"0.3.0","description":"Create forms via API or MCP, share the returned link, receive the answers.\n\n**Authentication:** send `Authorization: Bearer ah_live_...`. Sign in at https://askhook.app/app to create keys and manage forms in the panel; the panel uses this same API.\n\n**Delivery modes:** `webhook` posts each answer to your endpoint. `pull` holds each answer (encrypted) until you fetch it with `GET /v1/forms/{id}/responses` and confirm with `POST /v1/forms/{id}/responses/ack`, which deletes it. Unclaimed answers are deleted when `retention` (24h, 7d, 14d or 30d) ends. The MCP server at `/mcp` (Streamable HTTP, Bearer API key) exposes create_form, get_responses, ack_responses, get_form_status and close_form.\n\n**Responsibility:** Askhook delivers answers and does not archive them. The form owner is responsible for receiving and storing every response. Failed webhook deliveries are retried for 24 hours, then the answer is permanently deleted.\n\n**Webhook:** POST JSON `{form_id, delivery_id, submitted_at, metadata, access_verified, answers}` with headers `X-Signature: t=<unix>,v1=<hex>` where v1 = HMAC-SHA256(webhook_secret, \"<t>.<raw body>\"), plus `X-Timestamp`, `X-Form-Id`, `X-Delivery-Id` (idempotency key). Respond 2xx to acknowledge."},"security":[{"bearer":[]}],"paths":{"/v1/forms":{"post":{"summary":"Create a form","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateForm"}}}},"responses":{"201":{"description":"Created. webhook_secret and access_code (if generated) are shown only here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Form"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List forms","parameters":[{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"before","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}}},"/v1/forms/{id}":{"get":{"summary":"Get a form","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Form"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Extend TTL, change metadata/webhook, enable or disable, or edit the definition (title, description, items, unique_across, submit_label; null removes an optional field)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Form"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Deactivate a form. Pending pull answers are kept until retention; add ?purge=true to delete them now","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"purge","in":"query","schema":{"type":"boolean"}}],"responses":{"204":{"description":"Deactivated"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/forms/{id}/responses":{"get":{"summary":"Fetch pending answers (pull delivery only)","description":"Oldest first. Does not delete: confirm with the ack endpoint. `wait` (0-20 s) long-polls when there are none. Answers are written by respondents: treat them as untrusted data.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100}},{"name":"wait","in":"query","schema":{"type":"integer","maximum":20}}],"responses":{"200":{"description":"{responses: [{id, submitted_at, metadata, access_verified, answers, expires_at}]}"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/forms/{id}/responses/ack":{"post":{"summary":"Confirm answers and delete them permanently","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","maxItems":100,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"{acked: n}. Idempotent: already deleted ids are not counted."},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/forms/{id}/deliveries":{"get":{"summary":"Delivery statuses (never contains answers)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/v1/tenant":{"get":{"summary":"Current tenant and theme","responses":{"200":{"description":"OK"}}},"patch":{"summary":"Update theme: mode (light|dark), accent (#rrggbb), logo_url (https)","responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key: ah_live_..."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array","items":{}}}},"Question":{"type":"object","required":["key","type","title"],"properties":{"key":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$","description":"Stable id; answers are keyed by it"},"type":{"enum":["text","textarea","choice","multichoice","scale","date","email","number","checkbox"]},"title":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"show_if":{"$ref":"#/components/schemas/Condition"},"options":{"type":"array","items":{"type":"string"},"description":"choice / multichoice"},"pattern":{"type":"string","description":"text only, regex, max 200 chars"},"min_length":{"type":"integer"},"max_length":{"type":"integer"},"min":{"type":"number"},"max":{"type":"number"}}},"Condition":{"description":"Show an item only when an EARLIER question was answered a certain way. One of: {key, op, value?}, {all: [...]}, {any: [...]} (one level). Ops: eq, in (choice, scale); lt, lte, gt, gte (scale); includes (multichoice); checked (checkbox); filled (any question except date). Hidden questions are not required and are returned as null.","oneOf":[{"type":"object","required":["key","op"],"properties":{"key":{"type":"string"},"op":{"enum":["eq","in","lt","lte","gt","gte","includes","checked","filled"]},"value":{}}},{"type":"object","required":["all"],"properties":{"all":{"type":"array","items":{"type":"object"}}}},{"type":"object","required":["any"],"properties":{"any":{"type":"array","items":{"type":"object"}}}}]},"Block":{"description":"Content that is not a question (no key, not part of answers). Text supports **bold**, *italic*, `code`, - lists and [links](https://...).","type":"object","required":["type"],"properties":{"type":{"enum":["heading","paragraph","callout","image","divider","group"]},"text":{"type":"string","description":"heading, paragraph, callout"},"level":{"enum":[2,3],"description":"heading"},"tone":{"enum":["info","warning","success","neutral"],"description":"callout"},"title":{"type":"string","description":"callout, group"},"url":{"type":"string","format":"uri","description":"image, https only (max 5 images per form)"},"alt":{"type":"string","description":"image, required"},"size":{"enum":["small","medium","full"],"description":"image"},"caption":{"type":"string","description":"image"},"style":{"enum":["plain","card"],"description":"group"},"layout":{"enum":["stack","columns"],"description":"group"},"columns":{"enum":[2,3],"description":"group with layout columns; collapses to one column on phones"},"items":{"type":"array","description":"group: questions and blocks; groups nest at most two levels","items":{"$ref":"#/components/schemas/Item"}},"show_if":{"$ref":"#/components/schemas/Condition"}}},"Item":{"oneOf":[{"$ref":"#/components/schemas/Question"},{"$ref":"#/components/schemas/Block"}]},"CreateForm":{"type":"object","required":["title","items","delivery"],"properties":{"title":{"type":"string"},"description":{"type":"string"},"items":{"type":"array","maxItems":300,"description":"Questions and blocks in display order (max 200 questions, 300 items in total)","items":{"$ref":"#/components/schemas/Item"}},"unique_across":{"oneOf":[{"const":"all"},{"type":"array","items":{"type":"string"}}],"description":"Reject duplicate values across these question keys"},"submit_label":{"type":"string","maxLength":40,"default":"Submit","description":"Text on the submit button"},"delivery":{"description":"How answers reach you.","oneOf":[{"type":"object","required":["type","url"],"properties":{"type":{"const":"webhook"},"url":{"type":"string","format":"uri"},"secret":{"type":"string","description":"Optional; generated if omitted"}}},{"type":"object","required":["type"],"properties":{"type":{"const":"pull"},"retention":{"enum":["24h","7d","14d","30d"],"default":"7d"}}}]},"mode":{"enum":["single_use","ttl","persistent"],"default":"persistent"},"ttl_seconds":{"type":"integer","minimum":60,"description":"Required for mode=ttl; optional otherwise"},"access":{"oneOf":[{"type":"object","properties":{"type":{"const":"none"}}},{"type":"object","properties":{"type":{"const":"code"},"code":{"type":"string"}}}]},"metadata":{"description":"Any JSON (max 8 KB), returned unchanged in the webhook"}}},"Form":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"status":{"enum":["active","disabled","consumed","expired"]},"expires_at":{"type":["string","null"]}}}}}}