{"openapi":"3.1.0","info":{"title":"FormsList API","version":"1.0.0","description":"Form backend as a service. Instant no-auth provisioning for AI agents (/api/v1/instant), form submissions (/f/{hash}), and an authenticated management API. Errors on public endpoints include a \"fix\" field with the corrective action.","contact":{"url":"https://formslist.com/docs"}},"servers":[{"url":"https://formslist.com"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key prefixed ff_sk_ — create at https://formslist.com/account/api-keys"}},"schemas":{"AgentError":{"type":"object","properties":{"error":{"type":"string"},"fix":{"type":"string","description":"What to do instead — designed for AI agents to self-correct"},"docs_url":{"type":"string"}}},"Form":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"hash":{"type":"string"},"endpoint":{"type":"string"},"submission_count":{"type":"integer"},"is_active":{"type":"boolean"},"created_at":{"type":"string"}}}}},"paths":{"/api/v1/instant":{"post":{"summary":"Instantly provision a live form endpoint (no auth — built for AI agents)","description":"Creates a shadow account + form in one call. The endpoint works immediately; the site owner receives a claim email. Unclaimed forms expire after 7 days. Limits: 5/IP/day, 3/email/day.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"The SITE OWNER's real email — claim link + notifications go here"},"form_name":{"type":"string","default":"Contact form"}}}}}},"responses":{"201":{"description":"Form provisioned","content":{"application/json":{"schema":{"type":"object","properties":{"form_id":{"type":"string"},"endpoint":{"type":"string"},"method":{"type":"string"},"html_snippet":{"type":"string"},"curl_example":{"type":"string"},"claim_url":{"type":"string"},"expires_at":{"type":"string"},"docs_url":{"type":"string"},"note":{"type":"string"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"409":{"description":"Email already has a claimed account — use the authenticated API instead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}}}},"/f/{hash}":{"get":{"summary":"Self-documenting form endpoint — returns usage docs for this form","parameters":[{"name":"hash","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Usage documentation (JSON)"},"404":{"description":"Form not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}}},"post":{"summary":"Submit to a form","description":"Accepts JSON, form-urlencoded, or multipart. Special fields: _subject, _replyto, _next, honeypot (_gotcha by default — include hidden and empty). With Accept: application/json returns {ok:true}; browser posts get a 303 redirect.","parameters":[{"name":"hash","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"{ok: true, submission_id}"},"303":{"description":"Redirect (browser form posts)"},"422":{"description":"Validation failed: {ok:false, errors:[{field,message}]}"},"429":{"description":"Monthly submission limit reached"}}}},"/api/v1/forms":{"get":{"summary":"List forms","security":[{"apiKey":[]}],"responses":{"200":{"description":"{data: Form[], meta:{total}}"}}},"post":{"summary":"Create a form","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"{data: Form}"},"403":{"description":"Form limit reached (free plan: 5)"}}}},"/api/v1/forms/{formId}":{"get":{"summary":"Get a form","security":[{"apiKey":[]}],"parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{data: Form}"}}},"patch":{"summary":"Update form settings","security":[{"apiKey":[]}],"description":"Updatable: name, description, email_notifications, notification_emails, auto_response_* (Pro), redirect_url (Pro), allowed_domains (Pro), honeypot settings. Paid features return 402 {error:\"upgrade_required\"}.","parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{data: Form}"},"402":{"description":"Feature requires a paid plan"}}},"delete":{"summary":"Delete a form","security":[{"apiKey":[]}],"parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{data:{deleted:true}}"}}}},"/api/v1/forms/{formId}/submissions":{"get":{"summary":"List submissions","security":[{"apiKey":[]}],"parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","default":25,"maximum":100}}],"responses":{"200":{"description":"{data:[{id,data,is_spam,created_at, ai?:{score,tags}}], meta:{page,per_page,total,total_pages}} — \"ai\" lead scoring on paid plans"}}}},"/api/v1/submissions/{submissionId}":{"get":{"summary":"Get a submission","security":[{"apiKey":[]}],"parameters":[{"name":"submissionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{data: Submission}"}}}}}}