{"openapi":"3.1.0","info":{"title":"Superforms Actions API","version":"1.0.0","description":"Authenticated human-input infrastructure for AI agents. Create private structured form drafts, publish only after creator confirmation, send links to external people, and retrieve their durable asynchronous responses."},"externalDocs":{"description":"Superforms developer portal","url":"https://superforms.co/developers"},"tags":[{"name":"Drafts","description":"Private reviewable forms that do not yet have a public respondent link."},{"name":"Forms","description":"Published account-owned forms and asynchronous human responses."}],"servers":[{"url":"https://superforms.co/api/actions"}],"paths":{"/drafts":{"post":{"operationId":"createSuperformsDraft","tags":["Drafts"],"summary":"Create a private form draft","description":"Creates a private draft for review. It does not create a public link.","security":[{"oauth2":["forms:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormDraftInput"}}}},"responses":{"201":{"description":"Draft created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormDraft"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/drafts/{draftId}":{"patch":{"operationId":"updateSuperformsDraft","tags":["Drafts"],"summary":"Update a private form draft","description":"Replaces the supplied reviewable draft fields. The operation never publishes the draft or creates a public respondent URL.","security":[{"oauth2":["forms:write"]}],"parameters":[{"name":"draftId","in":"path","required":true,"description":"Identifier returned by createSuperformsDraft.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormDraftInput"}}}},"responses":{"200":{"description":"Draft updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormDraft"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/drafts/{draftId}/publish":{"post":{"operationId":"publishSuperformsDraft","tags":["Drafts"],"summary":"Publish a confirmed form draft","description":"Creates a public respondent link. Call only after the user confirms the draft.","security":[{"oauth2":["forms:write"]}],"parameters":[{"name":"draftId","in":"path","required":true,"description":"Confirmed private draft to publish.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Form published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishedForm"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/forms":{"get":{"operationId":"listSuperforms","tags":["Forms"],"summary":"List forms owned by the connected account","description":"Returns published forms owned by the OAuth-connected Superforms account, including response counts and the latest response timestamp.","security":[{"oauth2":["forms:read"]}],"responses":{"200":{"description":"Owned forms","content":{"application/json":{"schema":{"type":"object","properties":{"formCount":{"type":"integer"},"forms":{"type":"array","items":{"$ref":"#/components/schemas/FormSummary"}}},"required":["formCount","forms"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/forms/{formId}":{"get":{"operationId":"getSuperform","tags":["Forms"],"summary":"Get one owned form","description":"Returns the questions, response settings, public share URL, status, and response summary for one form owned by the connected account.","security":[{"oauth2":["forms:read"]}],"parameters":[{"name":"formId","in":"path","required":true,"description":"Published form identifier.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Form details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnedForm"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/forms/{formId}/responses":{"get":{"operationId":"getSuperformResponses","tags":["Forms"],"summary":"Get submitted responses for one owned form","description":"Returns durable response sessions and their raw answers. Use the since cursor when reconnecting so an agent can continue an asynchronous human-input workflow without replaying older answers.","security":[{"oauth2":["responses:read"]}],"parameters":[{"name":"formId","in":"path","required":true,"description":"Published form identifier.","schema":{"type":"string","minLength":1}},{"name":"since","in":"query","required":false,"description":"ISO timestamp cursor from a previous result.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Submitted responses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormResponses"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://superforms.co/oauth/authorize","tokenUrl":"https://superforms.co/api/oauth/token","scopes":{"forms:read":"Read forms owned by the connected account","responses:read":"Read responses submitted to owned forms","forms:write":"Create drafts and publish confirmed forms","offline_access":"Keep the connected account available in later conversations"}}}}},"schemas":{"Question":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"context":{"type":"string"}},"required":["text"],"additionalProperties":false},"OutputQuestion":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"context":{"type":"string"}},"required":["id","text"],"additionalProperties":false},"FormSettings":{"type":"object","properties":{"followUpMode":{"type":"string","enum":["none","smart","deep_dive"],"description":"For one question, first ask \"Want smart follow-up questions?\" If enabled, summarize relevant conversation context, ask what other context to include, and send the combined private context."},"responseMode":{"type":"string","enum":["voice_preferred","text_only","voice_only"]},"responseLimit":{"type":"string","enum":["one","multiple"]},"maxFollowupsPerQuestion":{"type":"integer"},"maxTotalQuestions":{"type":["integer","null"]}},"required":["followUpMode","responseMode","responseLimit","maxFollowupsPerQuestion","maxTotalQuestions"],"additionalProperties":false},"FormDraftInput":{"type":"object","properties":{"title":{"type":"string","maxLength":120},"goal":{"type":"string","maxLength":2000},"context":{"type":"string","maxLength":4000,"description":"Required when smart follow-ups are enabled. Summarize relevant non-sensitive host-conversation context and append any extra context the creator provides. Never shown to respondents."},"questions":{"type":"array","minItems":1,"maxItems":20,"items":{"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/Question"}]}},"followUpMode":{"type":"string","enum":["none","smart","deep_dive"],"description":"For one question, first ask \"Want smart follow-up questions?\" If enabled, summarize relevant conversation context, ask what other context to include, and send the combined private context."},"responseMode":{"type":"string","enum":["voice_preferred","text_only","voice_only"]},"responseLimit":{"type":"string","enum":["one","multiple"]},"maxFollowupsPerQuestion":{"type":"integer","minimum":0,"maximum":50},"maxTotalQuestions":{"type":"integer","minimum":0,"maximum":50}},"additionalProperties":false},"FormDraft":{"type":"object","properties":{"draftId":{"type":"string"},"status":{"type":"string","enum":["draft","published"]},"title":{"type":"string"},"goal":{"type":["string","null"]},"questions":{"type":"array","items":{"$ref":"#/components/schemas/OutputQuestion"}},"settings":{"$ref":"#/components/schemas/FormSettings"},"publishedFormId":{"type":["string","null"]},"shareUrl":{"type":["string","null"],"format":"uri"}},"required":["draftId","status","title","goal","questions","settings","publishedFormId","shareUrl"],"additionalProperties":false},"PublishedForm":{"type":"object","properties":{"formId":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"},"shareUrl":{"type":"string","format":"uri"},"questionCount":{"type":"integer"},"responseLimit":{"type":"string"},"idempotent":{"type":"boolean"}},"required":["formId","status","title","shareUrl","questionCount"],"additionalProperties":false},"FormSummary":{"type":"object","properties":{"formId":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"status":{"type":"string"},"questionCount":{"type":"integer"},"responseLimit":{"type":"string","enum":["one","multiple"]},"responseCount":{"type":"integer"},"latestResponseAt":{"type":["string","null"],"format":"date-time"},"publishedAt":{"type":"string","format":"date-time"}},"required":["formId","title","url","status","questionCount","responseLimit","responseCount","latestResponseAt","publishedAt"],"additionalProperties":false},"OwnedForm":{"type":"object","properties":{"formId":{"type":"string"},"title":{"type":"string"},"goal":{"type":["string","null"]},"questions":{"type":"array","items":{"$ref":"#/components/schemas/OutputQuestion"}},"settings":{"$ref":"#/components/schemas/FormSettings"},"shareUrl":{"type":"string","format":"uri"},"status":{"type":"string"},"responseCount":{"type":"integer"},"latestResponseAt":{"type":["string","null"],"format":"date-time"},"publishedAt":{"type":"string","format":"date-time"}},"required":["formId","title","goal","questions","settings","shareUrl","status","responseCount","latestResponseAt","publishedAt"],"additionalProperties":false},"ResponseAnswer":{"type":"object","properties":{"id":{"type":"string"},"questionId":{"type":"string"},"questionText":{"type":"string"},"answerText":{"type":"string"},"answerTruncated":{"type":"boolean"},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"size":{"type":"integer"},"contentOmitted":{"type":"boolean"}},"required":["id","name","type","size","contentOmitted"],"additionalProperties":false}},"responseType":{"type":"string","enum":["voice","text"]},"questionKind":{"type":"string","enum":["scripted","followup"]},"parentQuestionId":{"type":["string","null"]},"respondedAt":{"type":"string","format":"date-time"}},"required":["id","questionId","questionText","answerText","answerTruncated","attachments","responseType","questionKind","parentQuestionId","respondedAt"],"additionalProperties":false},"ResponseSession":{"type":"object","properties":{"sessionId":{"type":"string"},"responderName":{"type":["string","null"]},"status":{"type":"string"},"submittedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"answers":{"type":"array","items":{"$ref":"#/components/schemas/ResponseAnswer"}}},"required":["sessionId","responderName","status","submittedAt","createdAt","answers"],"additionalProperties":false},"ResponseForm":{"type":"object","properties":{"formId":{"type":"string"},"title":{"type":"string"},"goal":{"type":["string","null"]},"questions":{"type":"array","items":{"$ref":"#/components/schemas/OutputQuestion"}},"settings":{"$ref":"#/components/schemas/FormSettings"},"status":{"type":"string"}},"required":["formId","title","goal","questions","settings","status"],"additionalProperties":false},"FormResponses":{"type":"object","properties":{"form":{"$ref":"#/components/schemas/ResponseForm"},"status":{"type":"string"},"responseCount":{"type":"integer"},"returnedResponseCount":{"type":"integer"},"returnedAnswerCount":{"type":"integer"},"hasResponses":{"type":"boolean"},"latestResponseAt":{"type":["string","null"],"format":"date-time"},"nextSince":{"type":["string","null"],"format":"date-time"},"responses":{"type":"array","items":{"$ref":"#/components/schemas/ResponseSession"}},"truncated":{"type":"boolean"}},"required":["form","status","responseCount","returnedResponseCount","returnedAnswerCount","hasResponses","latestResponseAt","nextSince","responses","truncated"],"additionalProperties":false},"Error":{"type":"object","description":"Stable structured API error. error is retained as a backward-compatible alias for message.","properties":{"error":{"type":"string","description":"Backward-compatible human-readable error text."},"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation of the failure."},"resolution":{"type":"string","description":"Actionable hint for correcting or retrying the request."}},"required":["error","code","message","resolution"],"additionalProperties":false}},"responses":{"Error":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Connect the Superforms account or grant the required OAuth scope.","headers":{"WWW-Authenticate":{"description":"OAuth challenge with protected-resource metadata.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"The draft state conflicts with the requested operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many write operations were attempted.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}