{"openapi":"3.1.0","info":{"title":"Request Forms API","summary":"Public REST API for Request Forms on requestforms.io","description":"Request Forms hosts forms and collects answers. Unauthenticated routes cover health, platform stats, published forms, and public submits. Paid organization API keys (`Authorization: Bearer rfk_...`) list forms and responses. The website session cookie and the MCP server are separate from API keys. Support: support@requestforms.app. Docs: https://requestforms.io/docs/api. MCP: https://requestforms.io/mcp. CLI: https://requestforms.io/docs/cli. REST versioning: public discovery routes live at /api. Paid list routes live at /api/v1. A new major path such as /api/v2 is required for breaking changes. Deprecation policy: https://requestforms.io/docs/deprecation. Deprecation uses RFC 9745 Deprecation and RFC 8594 Sunset response headers on the old path before removal. There is no scheduled sunset for /api/v1.","version":"1.0.0","contact":{"name":"Request Forms support","email":"support@requestforms.app","url":"https://requestforms.io/contact"}},"externalDocs":{"description":"REST versioning, deprecation, and sunset policy. RFC 9745 Deprecation headers and RFC 8594 Sunset headers.","url":"https://requestforms.io/docs/deprecation"},"servers":[{"url":"https://requestforms.io","description":"Request Forms public origin"}],"tags":[{"name":"Discovery","description":"Find the API without an account."},{"name":"Public forms","description":"Read a published form and post answers."},{"name":"Auth","description":"Account register and provider list."},{"name":"API keys","description":"Paid organization read API."}],"paths":{"/api":{"get":{"operationId":"getApiCatalog","tags":["Discovery"],"summary":"Request Forms API catalog","description":"JSON index of public Request Forms endpoints, OpenAPI, docs, deprecation policy, CLI, and MCP. No auth.","parameters":[{"name":"Accept","in":"header","required":false,"description":"Clients should send application/json.","schema":{"type":"string","default":"application/json"}}],"responses":{"200":{"description":"Catalog of public Request Forms API links.","headers":{"Deprecation":{"description":"RFC 9745 Deprecation header. Omitted while this path is current. Set to an HTTP date when the path is deprecated.","schema":{"type":"string"},"required":false},"Sunset":{"description":"RFC 8594 Sunset header. Omitted while there is no removal date. Set to an HTTP date when the path will be removed.","schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/ApiCatalog"}]}}}}}}},"/api/health":{"get":{"operationId":"getApiHealth","tags":["Discovery"],"summary":"Request Forms API health","description":"Liveness JSON for the NestJS API behind requestforms.io/api.","parameters":[{"name":"Accept","in":"header","required":false,"description":"Clients should send application/json.","schema":{"type":"string","default":"application/json"}}],"responses":{"200":{"description":"API process is up.","headers":{"Deprecation":{"description":"RFC 9745 Deprecation header. Omitted while this path is current. Set to an HTTP date when the path is deprecated.","schema":{"type":"string"},"required":false},"Sunset":{"description":"RFC 8594 Sunset header. Omitted while there is no removal date. Set to an HTTP date when the path will be removed.","schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/ApiHealth"}]}}}}}}},"/api/public/stats":{"get":{"operationId":"getPublicPlatformStats","tags":["Discovery"],"summary":"Request Forms public platform stats","description":"Counts of forms, organizations, responses, and uploads. No auth. Used on the homepage.","parameters":[{"name":"Accept","in":"header","required":false,"description":"Clients should send application/json.","schema":{"type":"string","default":"application/json"}}],"responses":{"200":{"description":"Platform totals.","headers":{"Deprecation":{"description":"RFC 9745 Deprecation header. Omitted while this path is current. Set to an HTTP date when the path is deprecated.","schema":{"type":"string"},"required":false},"Sunset":{"description":"RFC 8594 Sunset header. Omitted while there is no removal date. Set to an HTTP date when the path will be removed.","schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/PlatformStats"}]}}}}}}},"/api/public/forms/{formId}":{"get":{"operationId":"getPublicForm","tags":["Public forms"],"summary":"Get a published Request Forms form","description":"Returns the published form payload for the hosted page and embed. Unpublished ids return an error.","parameters":[{"name":"Accept","in":"header","required":false,"description":"Clients should send application/json.","schema":{"type":"string","default":"application/json"}},{"name":"formId","in":"path","required":true,"description":"Public form id from the share URL.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Published form payload.","headers":{"Deprecation":{"description":"RFC 9745 Deprecation header. Omitted while this path is current. Set to an HTTP date when the path is deprecated.","schema":{"type":"string"},"required":false},"Sunset":{"description":"RFC 8594 Sunset header. Omitted while there is no removal date. Set to an HTTP date when the path will be removed.","schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/PublishedForm"}]}}}},"404":{"description":"Form is missing or not published.","headers":{"Deprecation":{"description":"RFC 9745 Deprecation header. Omitted while this path is current. Set to an HTTP date when the path is deprecated.","schema":{"type":"string"},"required":false},"Sunset":{"description":"RFC 8594 Sunset header. Omitted while there is no removal date. Set to an HTTP date when the path will be removed.","schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/forms/{formId}/responses":{"post":{"operationId":"submitPublicFormResponse","tags":["Public forms"],"summary":"Submit answers to a Request Forms form","description":"Public submit for a published form. Optional session JWT attaches the signed-in user. Rate limits apply per form and IP.","parameters":[{"name":"Accept","in":"header","required":false,"description":"Clients should send application/json.","schema":{"type":"string","default":"application/json"}},{"name":"formId","in":"path","required":true,"description":"Published form id.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/SubmitFormRequest"}]}}}},"responses":{"201":{"description":"Stored response.","headers":{"Deprecation":{"description":"RFC 9745 Deprecation header. Omitted while this path is current. Set to an HTTP date when the path is deprecated.","schema":{"type":"string"},"required":false},"Sunset":{"description":"RFC 8594 Sunset header. Omitted while there is no removal date. Set to an HTTP date when the path will be removed.","schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/SubmitAck"}]}}}},"400":{"description":"Validation failed.","headers":{"Deprecation":{"description":"RFC 9745 Deprecation header. Omitted while this path is current. Set to an HTTP date when the path is deprecated.","schema":{"type":"string"},"required":false},"Sunset":{"description":"RFC 8594 Sunset header. Omitted while there is no removal date. Set to an HTTP date when the path will be removed.","schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/ApiError"}]}}}},"429":{"description":"Submit rate limit.","headers":{"Deprecation":{"description":"RFC 9745 Deprecation header. Omitted while this path is current. Set to an HTTP date when the path is deprecated.","schema":{"type":"string"},"required":false},"Sunset":{"description":"RFC 8594 Sunset header. Omitted while there is no removal date. Set to an HTTP date when the path will be removed.","schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/auth/providers":{"get":{"operationId":"listAuthProviders","tags":["Auth"],"summary":"Request Forms auth providers","description":"Which sign-in methods are enabled on this deploy (password, Google, GitHub).","parameters":[{"name":"Accept","in":"header","required":false,"description":"Clients should send application/json.","schema":{"type":"string","default":"application/json"}}],"responses":{"200":{"description":"Enabled auth providers.","headers":{"Deprecation":{"description":"RFC 9745 Deprecation header. Omitted while this path is current. Set to an HTTP date when the path is deprecated.","schema":{"type":"string"},"required":false},"Sunset":{"description":"RFC 8594 Sunset header. Omitted while there is no removal date. Set to an HTTP date when the path will be removed.","schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/AuthProviders"}]}}}}}}},"/api/auth/register":{"post":{"operationId":"registerAccount","tags":["Auth"],"summary":"Register a Request Forms account","description":"Create an email-and-password account. Email verification is required before password login. Rate limited per IP.","parameters":[{"name":"Accept","in":"header","required":false,"description":"Clients should send application/json.","schema":{"type":"string","default":"application/json"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/RegisterAccountRequest"}]}}}},"responses":{"201":{"description":"Account created. Verification still required.","headers":{"Deprecation":{"description":"RFC 9745 Deprecation header. Omitted while this path is current. Set to an HTTP date when the path is deprecated.","schema":{"type":"string"},"required":false},"Sunset":{"description":"RFC 8594 Sunset header. Omitted while there is no removal date. Set to an HTTP date when the path will be removed.","schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/RegisterResult"}]}}}},"400":{"description":"Validation failed.","headers":{"Deprecation":{"description":"RFC 9745 Deprecation header. Omitted while this path is current. Set to an HTTP date when the path is deprecated.","schema":{"type":"string"},"required":false},"Sunset":{"description":"RFC 8594 Sunset header. Omitted while there is no removal date. Set to an HTTP date when the path will be removed.","schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/ApiError"}]}}}},"429":{"description":"Register rate limit.","headers":{"Deprecation":{"description":"RFC 9745 Deprecation header. Omitted while this path is current. Set to an HTTP date when the path is deprecated.","schema":{"type":"string"},"required":false},"Sunset":{"description":"RFC 8594 Sunset header. Omitted while there is no removal date. Set to an HTTP date when the path will be removed.","schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/v1/forms":{"get":{"operationId":"listOrganizationFormsWithApiKey","tags":["API keys"],"summary":"List Request Forms forms with an API key","description":"Paid organization feature. Send `Authorization: Bearer rfk_...`. Lists forms in the key's organization. Does not create or update forms.","security":[{"apiKey":[]}],"parameters":[{"name":"Accept","in":"header","required":false,"description":"Clients should send application/json.","schema":{"type":"string","default":"application/json"}},{"name":"Authorization","in":"header","required":true,"description":"Paid organization API key. Format: Bearer rfk_...","schema":{"type":"string","pattern":"^Bearer rfk_"}}],"responses":{"200":{"description":"Organization forms.","headers":{"Deprecation":{"description":"RFC 9745 Deprecation header. Omitted while this path is current. Set to an HTTP date when the path is deprecated.","schema":{"type":"string"},"required":false},"Sunset":{"description":"RFC 8594 Sunset header. Omitted while there is no removal date. Set to an HTTP date when the path will be removed.","schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","allOf":[{"$ref":"#/components/schemas/FormSummaryList"}]}}}},"401":{"description":"Missing or invalid API key.","headers":{"Deprecation":{"description":"RFC 9745 Deprecation header. Omitted while this path is current. Set to an HTTP date when the path is deprecated.","schema":{"type":"string"},"required":false},"Sunset":{"description":"RFC 8594 Sunset header. Omitted while there is no removal date. Set to an HTTP date when the path will be removed.","schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/v1/forms/{formId}/responses":{"get":{"operationId":"listFormResponsesWithApiKey","tags":["API keys"],"summary":"List Request Forms responses with an API key","description":"Paid organization feature. Send `Authorization: Bearer rfk_...`. Lists answers for one form in the key's organization.","security":[{"apiKey":[]}],"parameters":[{"name":"Accept","in":"header","required":false,"description":"Clients should send application/json.","schema":{"type":"string","default":"application/json"}},{"name":"Authorization","in":"header","required":true,"description":"Paid organization API key. Format: Bearer rfk_...","schema":{"type":"string","pattern":"^Bearer rfk_"}},{"name":"formId","in":"path","required":true,"description":"Form id in the API key's organization.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Form responses.","headers":{"Deprecation":{"description":"RFC 9745 Deprecation header. Omitted while this path is current. Set to an HTTP date when the path is deprecated.","schema":{"type":"string"},"required":false},"Sunset":{"description":"RFC 8594 Sunset header. Omitted while there is no removal date. Set to an HTTP date when the path will be removed.","schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","allOf":[{"$ref":"#/components/schemas/FormResponseSummaryList"}]}}}},"401":{"description":"Missing or invalid API key.","headers":{"Deprecation":{"description":"RFC 9745 Deprecation header. Omitted while this path is current. Set to an HTTP date when the path is deprecated.","schema":{"type":"string"},"required":false},"Sunset":{"description":"RFC 8594 Sunset header. Omitted while there is no removal date. Set to an HTTP date when the path will be removed.","schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/ApiError"}]}}}},"404":{"description":"Form is not in this organization.","headers":{"Deprecation":{"description":"RFC 9745 Deprecation header. Omitted while this path is current. Set to an HTTP date when the path is deprecated.","schema":{"type":"string"},"required":false},"Sunset":{"description":"RFC 8594 Sunset header. Omitted while there is no removal date. Set to an HTTP date when the path will be removed.","schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/ApiError"}]}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"rfk","description":"Paid organization API key. Header: `Authorization: Bearer rfk_...`. Session JWTs are rejected."}},"schemas":{"ApiError":{"type":"object","required":["statusCode","message"],"properties":{"statusCode":{"type":"integer"},"message":{"type":"string"},"error":{"type":"string"}}},"ApiCatalog":{"type":"object","required":["name","openapi","docs"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"openapi":{"type":"string","format":"uri"},"docs":{"type":"string","format":"uri"},"authDocs":{"type":"string","format":"uri"},"webhooks":{"type":"string","format":"uri"},"mcp":{"type":"string","format":"uri"},"mcpDocs":{"type":"string","format":"uri"},"mcpManifest":{"type":"string","format":"uri"},"mcpServerJson":{"type":"string","format":"uri"},"cli":{"type":"string","format":"uri"},"developers":{"type":"string","format":"uri"},"deprecation":{"type":"string","format":"uri"},"llms":{"type":"string","format":"uri"},"endpoints":{"type":"array","items":{"type":"string"}}}},"ApiHealth":{"type":"object","required":["status","service"],"properties":{"status":{"type":"string","enum":["ok"]},"service":{"type":"string"}}},"PlatformStats":{"type":"object","required":["formsCreated","organizations","responsesSubmitted","filesUploaded","formsExported","filesUploadedBytes"],"properties":{"formsCreated":{"type":"integer"},"organizations":{"type":"integer"},"responsesSubmitted":{"type":"integer"},"filesUploaded":{"type":"integer"},"formsExported":{"type":"integer"},"filesUploadedBytes":{"type":"integer"}}},"AuthProviders":{"type":"object","required":["password","google","github"],"properties":{"password":{"type":"boolean"},"google":{"type":"boolean"},"github":{"type":"boolean"}}},"RegisterAccountRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8,"maxLength":128},"name":{"type":"string","maxLength":120}}},"RegisterResult":{"type":"object","required":["verificationRequired"],"properties":{"verificationRequired":{"type":"boolean"},"user":{"type":"object","required":["id","email"],"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"}}}}},"PublishedForm":{"type":"object","required":["id","title","published"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"published":{"type":"boolean"},"definition":{"type":"object","description":"Form field tree used by the hosted page.","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/PublishedFormField"}}}}}},"PublishedFormField":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"type":"string"},"required":{"type":"boolean"}}},"SubmitFormRequest":{"type":"object","required":["answers"],"properties":{"answers":{"type":"object","description":"Map of field id to answer value.","additionalProperties":true},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"respondentEmail":{"type":"string","format":"email"},"captchaId":{"type":"string"},"captchaAnswer":{"type":"string"},"recaptchaToken":{"type":"string"},"website":{"type":"string","description":"Honeypot. Leave empty."}}},"SubmitAck":{"type":"object","required":["id","formId"],"properties":{"id":{"type":"string"},"formId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"FormSummary":{"type":"object","required":["id","title"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"published":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time"}}},"FormSummaryList":{"type":"array","items":{"$ref":"#/components/schemas/FormSummary"}},"FormResponseSummary":{"type":"object","required":["id","formId","createdAt"],"properties":{"id":{"type":"string"},"formId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"answers":{"type":"object","description":"Map of field id to stored answer.","additionalProperties":true}}},"FormResponseSummaryList":{"type":"array","items":{"$ref":"#/components/schemas/FormResponseSummary"}}}}}