Files
form/zipdoc_gen.go
zeekayandGitHub 8a94ddf049 form: a typed address is a claim, and a body is judged before it is read (#6)
A public submission is refused before its body is decoded when it is not JSON
(415), past its address's rate (429) or past the platform's bound (413), and a
body past 1 MiB is never decoded by any path: sixteen megabytes of empty answers
allocated three gigabytes.

An address typed into a form is the respondent's claim. Only a signed-in
person is verified. Under a form's identity setting, claimed (the default) files
the claim marked unverified and asks the list's double opt-in instead of joining
it or mailing a welcome; verified takes no claim at all. Every submission is its
own response, so a squatter cannot hold an address against its owner.

The CRM filing is recorded on the response, retried, listed by filed=false and
filed on demand. Webhooks run per org with a bounded queue, dial nothing in the
NAT64, 6to4, Teredo or reserved ranges, log no address, and sign a timestamp.
Numbers are bounded, summaries stay finite, retention counts from storing, a slug
is never adopted, format characters are dropped, CSV headers are escaped, and
the platform's default sinks mail nobody. The importer names its org and brings
forms in unpublished, mailing nobody.

Claude-Session: https://claude.ai/code/session_016DKtyuzxU43Gsc6Pm9vKTF
2026-11-02 06:33:25 -08:00

771 lines
78 KiB
Go

// Code generated by zipdoc; DO NOT EDIT.
package form
import (
"encoding/json"
"github.com/zap-proto/zip"
)
func init() {
zip.Describe("github.com/hanzoai/form DELETE /v1/form/forms/:id", zip.Doc{
Description: "Deletes a form with every response, webhook and delivery it has, and the\nwebhooks' signing secrets. An org admin only.",
Fields: map[string]string{
"FormRef.id": "ID is the form's id or its slug, from the path.",
},
})
zip.Describe("github.com/hanzoai/form DELETE /v1/form/forms/:id/responses/:response", zip.Doc{
Description: "Deletes one response of a form, and its webhook deliveries. What the sinks\nalready hold (the CRM's timeline, a webhook's receiver) is theirs. An org admin\nonly.",
Fields: map[string]string{
"ResponseRef.id": "ID is the form's id or slug, from the path.",
"ResponseRef.response": "Response is the response's id, from the path.",
},
})
zip.Describe("github.com/hanzoai/form DELETE /v1/form/forms/:id/webhooks/:webhook", zip.Doc{
Description: "Deletes a webhook, its deliveries and its secret. An org admin only.",
Fields: map[string]string{
"WebhookRef.id": "ID is the form's id or slug, from the path.",
"WebhookRef.webhook": "Webhook is the webhook's id, from the path.",
},
})
zip.Describe("github.com/hanzoai/form DELETE /v1/form/themes/:id", zip.Doc{
Description: "Deletes a theme. A form drawn in it is refused (409) until it names another,\nso no form is left naming a theme that is gone. An org admin only.",
Fields: map[string]string{
"ThemeRef.id": "ID is the theme's id, from the path.",
},
})
zip.Describe("github.com/hanzoai/form GET /v1/form/forms", zip.Doc{
Description: "Lists the caller org's forms, newest first, a page at a time; search keeps\nthe forms whose title holds it and tag the ones carrying it. An org admin only.",
Fields: map[string]string{
"CRM.company": "Company is the ref of the field whose answer is the person's company.",
"CRM.email": "Email is the ref of the field whose answer is the person's address.\nEmpty, the first email field is. A signed-in respondent is always the\naddress their account holds.",
"CRM.list": "List is the CRM list the person joins, by name (a subscribe form's\nmailing list). Empty joins none.",
"CRM.name": "Name is the ref of the field whose answer is the person's name.",
"Choice.id": "ID is the choice's id, assigned when empty.",
"Choice.label": "Label is the choice as shown. At most 200 characters.",
"Choice.ref": "Ref is how an answer names the choice; unique in the field, defaults to the id.",
"Field.choices": "Choices are what a multiple_choice or dropdown field offers, in order.",
"Field.description": "Description is the line under the question. At most 1000 characters.",
"Field.id": "ID is the field's id: assigned when a write leaves it empty, and kept\nacross edits by sending it back.",
"Field.labels": "Labels name the ends and middle of an opinion_scale.",
"Field.multiple": "Multiple is whether a multiple_choice field takes several choices.",
"Field.ref": "Ref is the field's stable name, how an answer and a sink name it:\nlowercase letters, digits, dash and underscore, at most 64, unique in the\nform. Defaults to the id.",
"Field.required": "Required is whether a completed response must answer it. A statement is\nnever required.",
"Field.start": "Start is where an opinion_scale begins: 0 (the default) or 1.",
"Field.steps": "Steps is how many points a rating (3 to 10, default 5) or an opinion_scale\n(5 to 11, default 11) has.",
"Field.title": "Title is the question as asked. At most 500 characters.",
"Field.type": "Type is one of short_text, long_text, email, phone, url, number, rating,\nopinion_scale, yes_no, multiple_choice, dropdown, date and statement.",
"Field.validations": "Validations bound an answer beyond its type.",
"Form.created": "Created is when the form was made, RFC 3339.",
"Form.fields": "Fields are the questions, in the order they are asked.",
"Form.hidden": "Hidden names the values a page passes in when it embeds the form (a video\nid, a plan): lowercase letters, digits and underscores, at most 32 each.",
"Form.id": "ID is the form's id: 15 lowercase hex characters, derived from the slug when\nthe form has one, so a slug names one form for good.",
"Form.kind": "Kind is form (every submission is a response, the default) or subscribe (a\nmailing list: an email field is required and one address is one response).",
"Form.public_id": "PublicID is the address the form is answered at: \"<org>.<slug or id>\", as\nGET /v1/form/public/{id} and POST /v1/form/public/{id}/responses take it.",
"Form.settings": "Settings is how the form is answered.",
"Form.sinks": "Sinks are where each completed response goes. Absent on a write, the\nplatform's defaults are taken.",
"Form.slug": "Slug is the form's own name within its org: lowercase letters, digits and\ndashes, at most 64. Optional; once set it is the form's id, so it cannot change.",
"Form.tags": "Tags label the form for its org: at most 20, each at most 64 characters.",
"Form.thanks": "Thanks is the screen shown after a submission, or where the respondent is\nsent. Optional.",
"Form.theme": "Theme is the id of the theme the form is drawn in. Optional.",
"Form.title": "Title is the form's name, as a respondent and the CRM timeline read it. At\nmost 200 characters.",
"Form.updated": "Updated is when it last changed, RFC 3339.",
"Form.welcome": "Welcome is the screen shown before the first question. Optional.",
"FormList.items": "Items are the forms, newest first.",
"FormList.page": "Page is this page, from 1.",
"FormList.page_size": "PageSize is how many a page holds.",
"FormList.total": "Total is how many forms answer the query.",
"FormsIn.page": "Page is the page, from 1. Default 1.",
"FormsIn.page_size": "PageSize is how many a page holds: at most 200, default 50.",
"FormsIn.search": "Search keeps the forms whose title holds it.",
"FormsIn.tag": "Tag keeps the forms tagged with it.",
"Forward.email": "Email is the address. Required.",
"Forward.name": "Name is who it is, for the greeting. Optional.",
"Options.identity": "Identity is who a response is from when nobody is signed in. claimed (the\ndefault): an address typed into an email field is the respondent's CLAIM,\nfiled on the CRM marked unverified, on the person it names only when the CRM\nalready holds them and without changing them; it joins no list and is mailed\nno welcome, and a list's consent is asked by the double opt-in instead.\nverified: only a signed-in respondent (their token) is anyone; a typed\naddress is an answer and nothing more. A signed-in respondent is verified\nunder either.",
"Options.language": "Language is the form's language, a tag like en or pt-BR. Default en.",
"Options.mode": "Mode is one (a question at a time, the default) or all (every question at once).",
"Options.progress": "Progress is whether the renderer shows a progress bar.",
"Options.visibility": "Visibility is public (answerable at its public address by anyone) or\nprivate (not served there). Default public.",
"Screen.button": "Button is the button's label. At most 64 characters.",
"Screen.description": "Description is the text under it. At most 2000 characters.",
"Screen.redirect": "Redirect is where a thank-you screen sends the respondent instead of\nshowing itself: an https address. Ignored on a welcome screen.",
"Screen.title": "Title is the screen's heading. At most 200 characters.",
"Sinks.crm": "CRM files the response on the timeline of the person it is from, or on the\norg's own timeline when it names nobody. Absent, nothing is filed.",
"Sinks.events": "Events states form_viewed, form_started and form_submitted on the\ndeployment's event stream: the form's ids and the refs of the fields\nanswered, never an answer's text.",
"Sinks.forward": "Forward mails every completed response to one address.",
"Sinks.welcome": "Welcome mails the respondent once, the first time their address answers.",
"Validations.max_length": "MaxLength is the most characters a text answer holds, at most the\nplatform's bound for the type.",
"Validations.max_value": "MaxValue is the most a number answer may be.",
"Validations.min_value": "MinValue is the least a number answer may be.",
"Welcome.body": "Body is the mail's text: plain text, a blank line a new paragraph. At most\n10000 characters.",
"Welcome.subject": "Subject is the mail's subject. At most 200 characters.",
},
})
zip.Describe("github.com/hanzoai/form GET /v1/form/forms/:id", zip.Doc{
Description: "Reads one form of the caller's org, by its id or its slug. An org admin only.",
Fields: map[string]string{
"CRM.company": "Company is the ref of the field whose answer is the person's company.",
"CRM.email": "Email is the ref of the field whose answer is the person's address.\nEmpty, the first email field is. A signed-in respondent is always the\naddress their account holds.",
"CRM.list": "List is the CRM list the person joins, by name (a subscribe form's\nmailing list). Empty joins none.",
"CRM.name": "Name is the ref of the field whose answer is the person's name.",
"Choice.id": "ID is the choice's id, assigned when empty.",
"Choice.label": "Label is the choice as shown. At most 200 characters.",
"Choice.ref": "Ref is how an answer names the choice; unique in the field, defaults to the id.",
"Field.choices": "Choices are what a multiple_choice or dropdown field offers, in order.",
"Field.description": "Description is the line under the question. At most 1000 characters.",
"Field.id": "ID is the field's id: assigned when a write leaves it empty, and kept\nacross edits by sending it back.",
"Field.labels": "Labels name the ends and middle of an opinion_scale.",
"Field.multiple": "Multiple is whether a multiple_choice field takes several choices.",
"Field.ref": "Ref is the field's stable name, how an answer and a sink name it:\nlowercase letters, digits, dash and underscore, at most 64, unique in the\nform. Defaults to the id.",
"Field.required": "Required is whether a completed response must answer it. A statement is\nnever required.",
"Field.start": "Start is where an opinion_scale begins: 0 (the default) or 1.",
"Field.steps": "Steps is how many points a rating (3 to 10, default 5) or an opinion_scale\n(5 to 11, default 11) has.",
"Field.title": "Title is the question as asked. At most 500 characters.",
"Field.type": "Type is one of short_text, long_text, email, phone, url, number, rating,\nopinion_scale, yes_no, multiple_choice, dropdown, date and statement.",
"Field.validations": "Validations bound an answer beyond its type.",
"Form.created": "Created is when the form was made, RFC 3339.",
"Form.fields": "Fields are the questions, in the order they are asked.",
"Form.hidden": "Hidden names the values a page passes in when it embeds the form (a video\nid, a plan): lowercase letters, digits and underscores, at most 32 each.",
"Form.id": "ID is the form's id: 15 lowercase hex characters, derived from the slug when\nthe form has one, so a slug names one form for good.",
"Form.kind": "Kind is form (every submission is a response, the default) or subscribe (a\nmailing list: an email field is required and one address is one response).",
"Form.public_id": "PublicID is the address the form is answered at: \"<org>.<slug or id>\", as\nGET /v1/form/public/{id} and POST /v1/form/public/{id}/responses take it.",
"Form.settings": "Settings is how the form is answered.",
"Form.sinks": "Sinks are where each completed response goes. Absent on a write, the\nplatform's defaults are taken.",
"Form.slug": "Slug is the form's own name within its org: lowercase letters, digits and\ndashes, at most 64. Optional; once set it is the form's id, so it cannot change.",
"Form.tags": "Tags label the form for its org: at most 20, each at most 64 characters.",
"Form.thanks": "Thanks is the screen shown after a submission, or where the respondent is\nsent. Optional.",
"Form.theme": "Theme is the id of the theme the form is drawn in. Optional.",
"Form.title": "Title is the form's name, as a respondent and the CRM timeline read it. At\nmost 200 characters.",
"Form.updated": "Updated is when it last changed, RFC 3339.",
"Form.welcome": "Welcome is the screen shown before the first question. Optional.",
"FormRef.id": "ID is the form's id or its slug, from the path.",
"Forward.email": "Email is the address. Required.",
"Forward.name": "Name is who it is, for the greeting. Optional.",
"Options.identity": "Identity is who a response is from when nobody is signed in. claimed (the\ndefault): an address typed into an email field is the respondent's CLAIM,\nfiled on the CRM marked unverified, on the person it names only when the CRM\nalready holds them and without changing them; it joins no list and is mailed\nno welcome, and a list's consent is asked by the double opt-in instead.\nverified: only a signed-in respondent (their token) is anyone; a typed\naddress is an answer and nothing more. A signed-in respondent is verified\nunder either.",
"Options.language": "Language is the form's language, a tag like en or pt-BR. Default en.",
"Options.mode": "Mode is one (a question at a time, the default) or all (every question at once).",
"Options.progress": "Progress is whether the renderer shows a progress bar.",
"Options.visibility": "Visibility is public (answerable at its public address by anyone) or\nprivate (not served there). Default public.",
"Screen.button": "Button is the button's label. At most 64 characters.",
"Screen.description": "Description is the text under it. At most 2000 characters.",
"Screen.redirect": "Redirect is where a thank-you screen sends the respondent instead of\nshowing itself: an https address. Ignored on a welcome screen.",
"Screen.title": "Title is the screen's heading. At most 200 characters.",
"Sinks.crm": "CRM files the response on the timeline of the person it is from, or on the\norg's own timeline when it names nobody. Absent, nothing is filed.",
"Sinks.events": "Events states form_viewed, form_started and form_submitted on the\ndeployment's event stream: the form's ids and the refs of the fields\nanswered, never an answer's text.",
"Sinks.forward": "Forward mails every completed response to one address.",
"Sinks.welcome": "Welcome mails the respondent once, the first time their address answers.",
"Validations.max_length": "MaxLength is the most characters a text answer holds, at most the\nplatform's bound for the type.",
"Validations.max_value": "MaxValue is the most a number answer may be.",
"Validations.min_value": "MinValue is the least a number answer may be.",
"Welcome.body": "Body is the mail's text: plain text, a blank line a new paragraph. At most\n10000 characters.",
"Welcome.subject": "Subject is the mail's subject. At most 200 characters.",
},
})
zip.Describe("github.com/hanzoai/form GET /v1/form/forms/:id/export", zip.Doc{
Description: "Exports a form's responses as JSON or CSV, a page of up to 5000 at a time\nunder the same filter a listing takes; next is the page to ask for after it,\n0 at the end. The CSV has one column per field (its title), then each hidden\nvalue, the respondent's address and kind, and when the response was landed on\nand submitted. An org admin only.",
Fields: map[string]string{
"Answer.field": "Field is the ref of the field answered.",
"Answer.type": "Type is the field's type. Set on a read; ignored on a write.",
"Export.csv": "CSV is the responses as CSV, for csv: one row each, one column per field,\nthen the hidden values, the respondent and the times.",
"Export.filename": "Filename is what to save it as.",
"Export.format": "Format is json or csv.",
"Export.items": "Items are the responses, for json.",
"Export.page": "Page is this page; Next the page after it, 0 when this is the last.",
"Export.total": "Total is how many responses answer the filter.",
"ExportIn.format": "Format is json (the default) or csv.",
"Respondent.email": "Email is the address the response is from: the account's, else the email\nfield's.",
"Respondent.kind": "Kind is account (a signed-in person, from their token), email (an email\nfield's answer), visitor (the page's visitor id) or none.",
"Respondent.person_id": "PersonID is the CRM person the address is: the one key a response, a list\nmembership, an email event and an experiment share. Every event and\ntimeline entry the service states carries it, never the address.",
"Respondent.subject": "Subject is the signed-in person's IAM subject.",
"Respondent.verified": "Verified is whether the respondent is who the response says: true only\nfor a signed-in person, from their token. A typed address is a claim.",
"Respondent.visitor": "Visitor is the page's visitor id.",
"Response.answers": "Answers are the answers, in the form's field order.",
"Response.completed": "Completed is whether the response was submitted whole; false is one saved\npart way.",
"Response.created": "Created is when the record was first written, RFC 3339.",
"Response.duration": "Duration is how many seconds lay between landing and submitting.",
"Response.external": "External is an imported response's id where it came from.",
"Response.filed": "Filed is whether a completed response is on the CRM's timeline. A filing\nthat failed is tried again on a schedule, and POST .../file tries it now.",
"Response.filing": "Filing is why the last filing failed; empty once it is filed.",
"Response.form": "Form is the form's id.",
"Response.hidden": "Hidden are the values the page passed in, by name.",
"Response.id": "ID is the response's id: derived from the form and the submission's token\n(from the form and the address on a subscribe form), so a retried\nsubmission is this same response.",
"Response.landed_at": "LandedAt is when the respondent opened the form, RFC 3339, as their page said.",
"Response.path": "Path is the page the form was answered on.",
"Response.respondent": "Respondent is who it is from.",
"Response.source": "Source is web, or import for a response brought in from elsewhere.",
"Response.submitted_at": "SubmittedAt is when the response was completed, RFC 3339.",
"Response.token": "Token is the submission token the response was made under.",
"Response.updated": "Updated is when it last changed, RFC 3339.",
"ResponsesIn.completed": "Completed keeps the completed responses (true) or the open ones (false);\nabsent keeps both.",
"ResponsesIn.excluded_response_ids": "ExcludedResponseIDs drops these responses, comma separated, at most 90.",
"ResponsesIn.filed": "Filed keeps the responses on the CRM's timeline (true) or not yet on it\n(false); absent keeps both.",
"ResponsesIn.id": "ID is the form's id or slug, from the path.",
"ResponsesIn.included_response_ids": "IncludedResponseIDs keeps only these responses, comma separated, at most 90.",
"ResponsesIn.page": "Page is the page, from 1. Default 1.",
"ResponsesIn.page_size": "PageSize is how many a page holds: at most 1000, default 25.",
"ResponsesIn.query": "Query keeps the responses whose answers hold it.",
"ResponsesIn.since": "Since keeps the responses made at or after it, RFC 3339.",
"ResponsesIn.sort": "Sort is submitted_at,desc (the default) or submitted_at,asc.",
"ResponsesIn.until": "Until keeps the responses made before it, RFC 3339.",
},
})
zip.Describe("github.com/hanzoai/form GET /v1/form/forms/:id/responses", zip.Doc{
Description: "Lists a form's responses, newest first, a page at a time: since and until\nbound when they were made, completed keeps the finished or the open ones, query\nkeeps the ones whose answers hold it, and included_response_ids and\nexcluded_response_ids keep or drop named ones. An org admin only.",
Fields: map[string]string{
"Answer.field": "Field is the ref of the field answered.",
"Answer.type": "Type is the field's type. Set on a read; ignored on a write.",
"Respondent.email": "Email is the address the response is from: the account's, else the email\nfield's.",
"Respondent.kind": "Kind is account (a signed-in person, from their token), email (an email\nfield's answer), visitor (the page's visitor id) or none.",
"Respondent.person_id": "PersonID is the CRM person the address is: the one key a response, a list\nmembership, an email event and an experiment share. Every event and\ntimeline entry the service states carries it, never the address.",
"Respondent.subject": "Subject is the signed-in person's IAM subject.",
"Respondent.verified": "Verified is whether the respondent is who the response says: true only\nfor a signed-in person, from their token. A typed address is a claim.",
"Respondent.visitor": "Visitor is the page's visitor id.",
"Response.answers": "Answers are the answers, in the form's field order.",
"Response.completed": "Completed is whether the response was submitted whole; false is one saved\npart way.",
"Response.created": "Created is when the record was first written, RFC 3339.",
"Response.duration": "Duration is how many seconds lay between landing and submitting.",
"Response.external": "External is an imported response's id where it came from.",
"Response.filed": "Filed is whether a completed response is on the CRM's timeline. A filing\nthat failed is tried again on a schedule, and POST .../file tries it now.",
"Response.filing": "Filing is why the last filing failed; empty once it is filed.",
"Response.form": "Form is the form's id.",
"Response.hidden": "Hidden are the values the page passed in, by name.",
"Response.id": "ID is the response's id: derived from the form and the submission's token\n(from the form and the address on a subscribe form), so a retried\nsubmission is this same response.",
"Response.landed_at": "LandedAt is when the respondent opened the form, RFC 3339, as their page said.",
"Response.path": "Path is the page the form was answered on.",
"Response.respondent": "Respondent is who it is from.",
"Response.source": "Source is web, or import for a response brought in from elsewhere.",
"Response.submitted_at": "SubmittedAt is when the response was completed, RFC 3339.",
"Response.token": "Token is the submission token the response was made under.",
"Response.updated": "Updated is when it last changed, RFC 3339.",
"ResponseList.items": "Items are the responses.",
"ResponseList.page": "Page is this page, from 1.",
"ResponseList.page_size": "PageSize is how many a page holds.",
"ResponseList.total": "Total is how many responses answer the filter.",
"ResponsesIn.completed": "Completed keeps the completed responses (true) or the open ones (false);\nabsent keeps both.",
"ResponsesIn.excluded_response_ids": "ExcludedResponseIDs drops these responses, comma separated, at most 90.",
"ResponsesIn.filed": "Filed keeps the responses on the CRM's timeline (true) or not yet on it\n(false); absent keeps both.",
"ResponsesIn.id": "ID is the form's id or slug, from the path.",
"ResponsesIn.included_response_ids": "IncludedResponseIDs keeps only these responses, comma separated, at most 90.",
"ResponsesIn.page": "Page is the page, from 1. Default 1.",
"ResponsesIn.page_size": "PageSize is how many a page holds: at most 1000, default 25.",
"ResponsesIn.query": "Query keeps the responses whose answers hold it.",
"ResponsesIn.since": "Since keeps the responses made at or after it, RFC 3339.",
"ResponsesIn.sort": "Sort is submitted_at,desc (the default) or submitted_at,asc.",
"ResponsesIn.until": "Until keeps the responses made before it, RFC 3339.",
},
})
zip.Describe("github.com/hanzoai/form GET /v1/form/forms/:id/responses/:response", zip.Doc{
Description: "Reads one response of a form. An org admin only.",
Fields: map[string]string{
"Answer.field": "Field is the ref of the field answered.",
"Answer.type": "Type is the field's type. Set on a read; ignored on a write.",
"Respondent.email": "Email is the address the response is from: the account's, else the email\nfield's.",
"Respondent.kind": "Kind is account (a signed-in person, from their token), email (an email\nfield's answer), visitor (the page's visitor id) or none.",
"Respondent.person_id": "PersonID is the CRM person the address is: the one key a response, a list\nmembership, an email event and an experiment share. Every event and\ntimeline entry the service states carries it, never the address.",
"Respondent.subject": "Subject is the signed-in person's IAM subject.",
"Respondent.verified": "Verified is whether the respondent is who the response says: true only\nfor a signed-in person, from their token. A typed address is a claim.",
"Respondent.visitor": "Visitor is the page's visitor id.",
"Response.answers": "Answers are the answers, in the form's field order.",
"Response.completed": "Completed is whether the response was submitted whole; false is one saved\npart way.",
"Response.created": "Created is when the record was first written, RFC 3339.",
"Response.duration": "Duration is how many seconds lay between landing and submitting.",
"Response.external": "External is an imported response's id where it came from.",
"Response.filed": "Filed is whether a completed response is on the CRM's timeline. A filing\nthat failed is tried again on a schedule, and POST .../file tries it now.",
"Response.filing": "Filing is why the last filing failed; empty once it is filed.",
"Response.form": "Form is the form's id.",
"Response.hidden": "Hidden are the values the page passed in, by name.",
"Response.id": "ID is the response's id: derived from the form and the submission's token\n(from the form and the address on a subscribe form), so a retried\nsubmission is this same response.",
"Response.landed_at": "LandedAt is when the respondent opened the form, RFC 3339, as their page said.",
"Response.path": "Path is the page the form was answered on.",
"Response.respondent": "Respondent is who it is from.",
"Response.source": "Source is web, or import for a response brought in from elsewhere.",
"Response.submitted_at": "SubmittedAt is when the response was completed, RFC 3339.",
"Response.token": "Token is the submission token the response was made under.",
"Response.updated": "Updated is when it last changed, RFC 3339.",
"ResponseRef.id": "ID is the form's id or slug, from the path.",
"ResponseRef.response": "Response is the response's id, from the path.",
},
})
zip.Describe("github.com/hanzoai/form GET /v1/form/forms/:id/summary", zip.Doc{
Description: "Sums up a form's responses: how many were begun and completed, and for each\nfield how many answered it, the distribution of what was said (choices,\npoints, yes and no), the mean, least and most of a number, and how many open\nresponses stopped in front of it. since and until narrow it to when the\nresponses were made. At most the newest 50000 are read, and truncated says so.\nAn org admin only.",
Fields: map[string]string{
"FieldSummary.answered": "Answered is how many responses answer it.",
"FieldSummary.distribution": "Distribution counts each value: every choice of a multiple_choice or\ndropdown (with its label), every point of a rating or opinion_scale, and\nyes and no.",
"FieldSummary.drop_off": "DropOff is how many open responses stopped in front of it: this is the\nfirst field they left unanswered after the last one they answered.",
"FieldSummary.field": "Field is the field's ref; Type its type; Title its question.",
"FieldSummary.mean": "Mean, Min and Max are a number, rating or opinion_scale's.",
"Summary.completion_rate": "CompletionRate is completions over starts, 0 to 1.",
"Summary.completions": "Completions is how many were completed.",
"Summary.fields": "Fields are each asked field's figures, in form order.",
"Summary.form": "Form is the form's id.",
"Summary.scanned": "Scanned is how many responses were read; Truncated says the form has more\nthan one summary reads (50000), and the newest were read.",
"Summary.starts": "Starts is how many responses were begun: open and completed.",
"Summary.views": "Views is null: a view is stated on the event stream as form_viewed and\ncounted there, not kept with the responses.",
"SummaryIn.id": "ID is the form's id or slug, from the path.",
"SummaryIn.since": "Since keeps the responses made at or after it, RFC 3339.",
"SummaryIn.until": "Until keeps the responses made before it, RFC 3339.",
},
})
zip.Describe("github.com/hanzoai/form GET /v1/form/forms/:id/webhooks", zip.Doc{
Description: "Lists a form's webhooks. Secrets are never read back. An org admin only.",
Fields: map[string]string{
"FormRef.id": "ID is the form's id or its slug, from the path.",
"Webhook.created": "Created is when the webhook was made, RFC 3339.",
"Webhook.enabled": "Enabled is whether responses are posted.",
"Webhook.form": "Form is the form's id.",
"Webhook.id": "ID is the webhook's id.",
"Webhook.secret": "Secret is the signing secret, answered once: when the webhook is made or\nits secret is set or rotated. Every delivery carries Hanzo-Signature:\nt=<unix seconds>,sha256=<base64 of HMAC-SHA256(secret, \"<seconds>.\" + body)>;\na receiver refuses one older than five minutes. It is kept in KMS and never\nread back.",
"Webhook.tag": "Tag names the webhook in its form. At most 64 characters.",
"Webhook.updated": "Updated is when it last changed, RFC 3339.",
"Webhook.url": "URL is the https address posted to.",
},
})
zip.Describe("github.com/hanzoai/form GET /v1/form/forms/:id/webhooks/:webhook", zip.Doc{
Description: "Reads one webhook of a form. Its secret is never read back. An org admin only.",
Fields: map[string]string{
"Webhook.created": "Created is when the webhook was made, RFC 3339.",
"Webhook.enabled": "Enabled is whether responses are posted.",
"Webhook.form": "Form is the form's id.",
"Webhook.id": "ID is the webhook's id.",
"Webhook.secret": "Secret is the signing secret, answered once: when the webhook is made or\nits secret is set or rotated. Every delivery carries Hanzo-Signature:\nt=<unix seconds>,sha256=<base64 of HMAC-SHA256(secret, \"<seconds>.\" + body)>;\na receiver refuses one older than five minutes. It is kept in KMS and never\nread back.",
"Webhook.tag": "Tag names the webhook in its form. At most 64 characters.",
"Webhook.updated": "Updated is when it last changed, RFC 3339.",
"Webhook.url": "URL is the https address posted to.",
"WebhookRef.id": "ID is the form's id or slug, from the path.",
"WebhookRef.webhook": "Webhook is the webhook's id, from the path.",
},
})
zip.Describe("github.com/hanzoai/form GET /v1/form/forms/:id/webhooks/:webhook/deliveries", zip.Doc{
Description: "Lists a webhook's deliveries, newest first: each response posted, how many\nattempts it took, the last status the address answered and why it failed. An\norg admin only.",
Fields: map[string]string{
"DeliveriesIn.id": "ID is the form's id or slug, from the path.",
"DeliveriesIn.page": "Page is the page, from 1; PageSize at most 200, default 50.",
"DeliveriesIn.webhook": "Webhook is the webhook's id, from the path.",
"Delivery.attempts": "Attempts is how many posts were made.",
"Delivery.code": "Code is the last HTTP status the address answered; 0 when it did not answer.",
"Delivery.created": "Created is when the first attempt was made, RFC 3339.",
"Delivery.error": "Error is why the last attempt failed.",
"Delivery.id": "ID is the delivery's id; the body carries it as event_id.",
"Delivery.next": "Next is when the next attempt is due, RFC 3339; empty when none is.",
"Delivery.response": "Response is the response's id.",
"Delivery.status": "Status is delivered, retrying or failed.",
"Delivery.updated": "Updated is when the last was, RFC 3339.",
"Delivery.webhook": "Webhook is the webhook's id.",
},
})
zip.Describe("github.com/hanzoai/form GET /v1/form/public/:id", zip.Doc{
Description: "Reads a published form as its page draws it: the questions, the screens, the\nhidden values it takes, how it is answered and its theme. Nothing about where\nits responses go. No credential is needed; a form that is private, deleted or\nnever was is a 404.",
Fields: map[string]string{
"Choice.id": "ID is the choice's id, assigned when empty.",
"Choice.label": "Label is the choice as shown. At most 200 characters.",
"Choice.ref": "Ref is how an answer names the choice; unique in the field, defaults to the id.",
"Drawn.language": "Language is the form's language tag.",
"Drawn.mode": "Mode is one (a question at a time) or all.",
"Drawn.progress": "Progress is whether a progress bar is shown.",
"Field.choices": "Choices are what a multiple_choice or dropdown field offers, in order.",
"Field.description": "Description is the line under the question. At most 1000 characters.",
"Field.id": "ID is the field's id: assigned when a write leaves it empty, and kept\nacross edits by sending it back.",
"Field.labels": "Labels name the ends and middle of an opinion_scale.",
"Field.multiple": "Multiple is whether a multiple_choice field takes several choices.",
"Field.ref": "Ref is the field's stable name, how an answer and a sink name it:\nlowercase letters, digits, dash and underscore, at most 64, unique in the\nform. Defaults to the id.",
"Field.required": "Required is whether a completed response must answer it. A statement is\nnever required.",
"Field.start": "Start is where an opinion_scale begins: 0 (the default) or 1.",
"Field.steps": "Steps is how many points a rating (3 to 10, default 5) or an opinion_scale\n(5 to 11, default 11) has.",
"Field.title": "Title is the question as asked. At most 500 characters.",
"Field.type": "Type is one of short_text, long_text, email, phone, url, number, rating,\nopinion_scale, yes_no, multiple_choice, dropdown, date and statement.",
"Field.validations": "Validations bound an answer beyond its type.",
"PublicForm.fields": "Fields are the questions, in order.",
"PublicForm.hidden": "Hidden names the values the page passes in.",
"PublicForm.id": "ID is the form's public id.",
"PublicForm.kind": "Kind is form or subscribe.",
"PublicForm.settings": "Settings are how the form is answered.",
"PublicForm.thanks": "Thanks is the screen after a submission, or where the respondent is sent.",
"PublicForm.theme": "Theme is the theme the form is drawn in, when it names one.",
"PublicForm.title": "Title is the form's title.",
"PublicForm.welcome": "Welcome is the screen before the first question.",
"PublicRef.id": "ID is the form's public id, \"<org>.<slug or id>\", from the path.",
"Screen.button": "Button is the button's label. At most 64 characters.",
"Screen.description": "Description is the text under it. At most 2000 characters.",
"Screen.redirect": "Redirect is where a thank-you screen sends the respondent instead of\nshowing itself: an https address. Ignored on a welcome screen.",
"Screen.title": "Title is the screen's heading. At most 200 characters.",
"Theme.background": "Background is an https address of an image drawn behind the form. Optional.",
"Theme.colors": "Colors are the theme's colours, each #rrggbb.",
"Theme.created": "Created is when the theme was made, RFC 3339.",
"Theme.font": "Font is the font family the form is set in: letters, digits, spaces and\ndashes, at most 64. Empty is the renderer's own.",
"Theme.id": "ID is the theme's id.",
"Theme.name": "Name is the theme's name in its org. At most 100 characters.",
"Theme.updated": "Updated is when it last changed, RFC 3339.",
"Validations.max_length": "MaxLength is the most characters a text answer holds, at most the\nplatform's bound for the type.",
"Validations.max_value": "MaxValue is the most a number answer may be.",
"Validations.min_value": "MinValue is the least a number answer may be.",
},
})
zip.Describe("github.com/hanzoai/form GET /v1/form/themes", zip.Doc{
Description: "Lists the caller org's themes by name. An org admin only.",
Fields: map[string]string{
"Theme.background": "Background is an https address of an image drawn behind the form. Optional.",
"Theme.colors": "Colors are the theme's colours, each #rrggbb.",
"Theme.created": "Created is when the theme was made, RFC 3339.",
"Theme.font": "Font is the font family the form is set in: letters, digits, spaces and\ndashes, at most 64. Empty is the renderer's own.",
"Theme.id": "ID is the theme's id.",
"Theme.name": "Name is the theme's name in its org. At most 100 characters.",
"Theme.updated": "Updated is when it last changed, RFC 3339.",
"ThemeList.items": "Items are the themes, by name.",
},
})
zip.Describe("github.com/hanzoai/form GET /v1/form/themes/:id", zip.Doc{
Description: "Reads one theme of the caller's org. An org admin only.",
Fields: map[string]string{
"Theme.background": "Background is an https address of an image drawn behind the form. Optional.",
"Theme.colors": "Colors are the theme's colours, each #rrggbb.",
"Theme.created": "Created is when the theme was made, RFC 3339.",
"Theme.font": "Font is the font family the form is set in: letters, digits, spaces and\ndashes, at most 64. Empty is the renderer's own.",
"Theme.id": "ID is the theme's id.",
"Theme.name": "Name is the theme's name in its org. At most 100 characters.",
"Theme.updated": "Updated is when it last changed, RFC 3339.",
"ThemeRef.id": "ID is the theme's id, from the path.",
},
})
zip.Describe("github.com/hanzoai/form PATCH /v1/form/forms/:id", zip.Doc{
Description: "Changes the parts of a form the body names and keeps the rest, then answers it\nas stored. The whole form is checked as it will be, exactly as a replace is.\nAn org admin only.",
Fields: map[string]string{
"CRM.company": "Company is the ref of the field whose answer is the person's company.",
"CRM.email": "Email is the ref of the field whose answer is the person's address.\nEmpty, the first email field is. A signed-in respondent is always the\naddress their account holds.",
"CRM.list": "List is the CRM list the person joins, by name (a subscribe form's\nmailing list). Empty joins none.",
"CRM.name": "Name is the ref of the field whose answer is the person's name.",
"Choice.id": "ID is the choice's id, assigned when empty.",
"Choice.label": "Label is the choice as shown. At most 200 characters.",
"Choice.ref": "Ref is how an answer names the choice; unique in the field, defaults to the id.",
"Field.choices": "Choices are what a multiple_choice or dropdown field offers, in order.",
"Field.description": "Description is the line under the question. At most 1000 characters.",
"Field.id": "ID is the field's id: assigned when a write leaves it empty, and kept\nacross edits by sending it back.",
"Field.labels": "Labels name the ends and middle of an opinion_scale.",
"Field.multiple": "Multiple is whether a multiple_choice field takes several choices.",
"Field.ref": "Ref is the field's stable name, how an answer and a sink name it:\nlowercase letters, digits, dash and underscore, at most 64, unique in the\nform. Defaults to the id.",
"Field.required": "Required is whether a completed response must answer it. A statement is\nnever required.",
"Field.start": "Start is where an opinion_scale begins: 0 (the default) or 1.",
"Field.steps": "Steps is how many points a rating (3 to 10, default 5) or an opinion_scale\n(5 to 11, default 11) has.",
"Field.title": "Title is the question as asked. At most 500 characters.",
"Field.type": "Type is one of short_text, long_text, email, phone, url, number, rating,\nopinion_scale, yes_no, multiple_choice, dropdown, date and statement.",
"Field.validations": "Validations bound an answer beyond its type.",
"Form.created": "Created is when the form was made, RFC 3339.",
"Form.fields": "Fields are the questions, in the order they are asked.",
"Form.hidden": "Hidden names the values a page passes in when it embeds the form (a video\nid, a plan): lowercase letters, digits and underscores, at most 32 each.",
"Form.id": "ID is the form's id: 15 lowercase hex characters, derived from the slug when\nthe form has one, so a slug names one form for good.",
"Form.kind": "Kind is form (every submission is a response, the default) or subscribe (a\nmailing list: an email field is required and one address is one response).",
"Form.public_id": "PublicID is the address the form is answered at: \"<org>.<slug or id>\", as\nGET /v1/form/public/{id} and POST /v1/form/public/{id}/responses take it.",
"Form.settings": "Settings is how the form is answered.",
"Form.sinks": "Sinks are where each completed response goes. Absent on a write, the\nplatform's defaults are taken.",
"Form.slug": "Slug is the form's own name within its org: lowercase letters, digits and\ndashes, at most 64. Optional; once set it is the form's id, so it cannot change.",
"Form.tags": "Tags label the form for its org: at most 20, each at most 64 characters.",
"Form.thanks": "Thanks is the screen shown after a submission, or where the respondent is\nsent. Optional.",
"Form.theme": "Theme is the id of the theme the form is drawn in. Optional.",
"Form.title": "Title is the form's name, as a respondent and the CRM timeline read it. At\nmost 200 characters.",
"Form.updated": "Updated is when it last changed, RFC 3339.",
"Form.welcome": "Welcome is the screen shown before the first question. Optional.",
"FormPatch.id": "ID is the form's id or its slug, from the path.",
"Forward.email": "Email is the address. Required.",
"Forward.name": "Name is who it is, for the greeting. Optional.",
"Options.identity": "Identity is who a response is from when nobody is signed in. claimed (the\ndefault): an address typed into an email field is the respondent's CLAIM,\nfiled on the CRM marked unverified, on the person it names only when the CRM\nalready holds them and without changing them; it joins no list and is mailed\nno welcome, and a list's consent is asked by the double opt-in instead.\nverified: only a signed-in respondent (their token) is anyone; a typed\naddress is an answer and nothing more. A signed-in respondent is verified\nunder either.",
"Options.language": "Language is the form's language, a tag like en or pt-BR. Default en.",
"Options.mode": "Mode is one (a question at a time, the default) or all (every question at once).",
"Options.progress": "Progress is whether the renderer shows a progress bar.",
"Options.visibility": "Visibility is public (answerable at its public address by anyone) or\nprivate (not served there). Default public.",
"Screen.button": "Button is the button's label. At most 64 characters.",
"Screen.description": "Description is the text under it. At most 2000 characters.",
"Screen.redirect": "Redirect is where a thank-you screen sends the respondent instead of\nshowing itself: an https address. Ignored on a welcome screen.",
"Screen.title": "Title is the screen's heading. At most 200 characters.",
"Sinks.crm": "CRM files the response on the timeline of the person it is from, or on the\norg's own timeline when it names nobody. Absent, nothing is filed.",
"Sinks.events": "Events states form_viewed, form_started and form_submitted on the\ndeployment's event stream: the form's ids and the refs of the fields\nanswered, never an answer's text.",
"Sinks.forward": "Forward mails every completed response to one address.",
"Sinks.welcome": "Welcome mails the respondent once, the first time their address answers.",
"Validations.max_length": "MaxLength is the most characters a text answer holds, at most the\nplatform's bound for the type.",
"Validations.max_value": "MaxValue is the most a number answer may be.",
"Validations.min_value": "MinValue is the least a number answer may be.",
"Welcome.body": "Body is the mail's text: plain text, a blank line a new paragraph. At most\n10000 characters.",
"Welcome.subject": "Subject is the mail's subject. At most 200 characters.",
},
})
zip.Describe("github.com/hanzoai/form POST /v1/form/forms", zip.Doc{
Description: "Makes a form in the caller's org and answers it as stored, its fields' ids\nassigned and its defaults filled: kind form, visibility public, language en,\none question at a time, and the platform's default sinks when it names none.\n\nA slug, when given, is the form's id for good: a second form with the same\nslug is refused (409). Every problem with the form is named at once (400). An\norg admin only.",
Fields: map[string]string{
"CRM.company": "Company is the ref of the field whose answer is the person's company.",
"CRM.email": "Email is the ref of the field whose answer is the person's address.\nEmpty, the first email field is. A signed-in respondent is always the\naddress their account holds.",
"CRM.list": "List is the CRM list the person joins, by name (a subscribe form's\nmailing list). Empty joins none.",
"CRM.name": "Name is the ref of the field whose answer is the person's name.",
"Choice.id": "ID is the choice's id, assigned when empty.",
"Choice.label": "Label is the choice as shown. At most 200 characters.",
"Choice.ref": "Ref is how an answer names the choice; unique in the field, defaults to the id.",
"Field.choices": "Choices are what a multiple_choice or dropdown field offers, in order.",
"Field.description": "Description is the line under the question. At most 1000 characters.",
"Field.id": "ID is the field's id: assigned when a write leaves it empty, and kept\nacross edits by sending it back.",
"Field.labels": "Labels name the ends and middle of an opinion_scale.",
"Field.multiple": "Multiple is whether a multiple_choice field takes several choices.",
"Field.ref": "Ref is the field's stable name, how an answer and a sink name it:\nlowercase letters, digits, dash and underscore, at most 64, unique in the\nform. Defaults to the id.",
"Field.required": "Required is whether a completed response must answer it. A statement is\nnever required.",
"Field.start": "Start is where an opinion_scale begins: 0 (the default) or 1.",
"Field.steps": "Steps is how many points a rating (3 to 10, default 5) or an opinion_scale\n(5 to 11, default 11) has.",
"Field.title": "Title is the question as asked. At most 500 characters.",
"Field.type": "Type is one of short_text, long_text, email, phone, url, number, rating,\nopinion_scale, yes_no, multiple_choice, dropdown, date and statement.",
"Field.validations": "Validations bound an answer beyond its type.",
"Form.created": "Created is when the form was made, RFC 3339.",
"Form.fields": "Fields are the questions, in the order they are asked.",
"Form.hidden": "Hidden names the values a page passes in when it embeds the form (a video\nid, a plan): lowercase letters, digits and underscores, at most 32 each.",
"Form.id": "ID is the form's id: 15 lowercase hex characters, derived from the slug when\nthe form has one, so a slug names one form for good.",
"Form.kind": "Kind is form (every submission is a response, the default) or subscribe (a\nmailing list: an email field is required and one address is one response).",
"Form.public_id": "PublicID is the address the form is answered at: \"<org>.<slug or id>\", as\nGET /v1/form/public/{id} and POST /v1/form/public/{id}/responses take it.",
"Form.settings": "Settings is how the form is answered.",
"Form.sinks": "Sinks are where each completed response goes. Absent on a write, the\nplatform's defaults are taken.",
"Form.slug": "Slug is the form's own name within its org: lowercase letters, digits and\ndashes, at most 64. Optional; once set it is the form's id, so it cannot change.",
"Form.tags": "Tags label the form for its org: at most 20, each at most 64 characters.",
"Form.thanks": "Thanks is the screen shown after a submission, or where the respondent is\nsent. Optional.",
"Form.theme": "Theme is the id of the theme the form is drawn in. Optional.",
"Form.title": "Title is the form's name, as a respondent and the CRM timeline read it. At\nmost 200 characters.",
"Form.updated": "Updated is when it last changed, RFC 3339.",
"Form.welcome": "Welcome is the screen shown before the first question. Optional.",
"Forward.email": "Email is the address. Required.",
"Forward.name": "Name is who it is, for the greeting. Optional.",
"Options.identity": "Identity is who a response is from when nobody is signed in. claimed (the\ndefault): an address typed into an email field is the respondent's CLAIM,\nfiled on the CRM marked unverified, on the person it names only when the CRM\nalready holds them and without changing them; it joins no list and is mailed\nno welcome, and a list's consent is asked by the double opt-in instead.\nverified: only a signed-in respondent (their token) is anyone; a typed\naddress is an answer and nothing more. A signed-in respondent is verified\nunder either.",
"Options.language": "Language is the form's language, a tag like en or pt-BR. Default en.",
"Options.mode": "Mode is one (a question at a time, the default) or all (every question at once).",
"Options.progress": "Progress is whether the renderer shows a progress bar.",
"Options.visibility": "Visibility is public (answerable at its public address by anyone) or\nprivate (not served there). Default public.",
"Screen.button": "Button is the button's label. At most 64 characters.",
"Screen.description": "Description is the text under it. At most 2000 characters.",
"Screen.redirect": "Redirect is where a thank-you screen sends the respondent instead of\nshowing itself: an https address. Ignored on a welcome screen.",
"Screen.title": "Title is the screen's heading. At most 200 characters.",
"Sinks.crm": "CRM files the response on the timeline of the person it is from, or on the\norg's own timeline when it names nobody. Absent, nothing is filed.",
"Sinks.events": "Events states form_viewed, form_started and form_submitted on the\ndeployment's event stream: the form's ids and the refs of the fields\nanswered, never an answer's text.",
"Sinks.forward": "Forward mails every completed response to one address.",
"Sinks.welcome": "Welcome mails the respondent once, the first time their address answers.",
"Validations.max_length": "MaxLength is the most characters a text answer holds, at most the\nplatform's bound for the type.",
"Validations.max_value": "MaxValue is the most a number answer may be.",
"Validations.min_value": "MinValue is the least a number answer may be.",
"Welcome.body": "Body is the mail's text: plain text, a blank line a new paragraph. At most\n10000 characters.",
"Welcome.subject": "Subject is the mail's subject. At most 200 characters.",
},
Example: json.RawMessage(`{"slug":"video-feedback","title":"How was the video?","fields":[{"ref":"rating","type":"rating","title":"Rate the video","required":true},{"ref":"comment","type":"long_text","title":"Anything to tell us?"}],"hidden":["video"]}`),
})
zip.Describe("github.com/hanzoai/form POST /v1/form/forms/:id/import", zip.Doc{
Description: "Brings responses made elsewhere into a form, keeping when each was made, a\nbatch of at most 500 at a time. Each is keyed by its external id (on a\nsubscribe form, by its address), so a batch sent again, or an import resumed\nfrom any point, makes nothing twice. Each answer is read against its field as\na submission's is; a required field may be unanswered. With file, each new\nresponse is also filed in the CRM at the time it was made; nothing is mailed\nand no webhook is told. An org admin only.",
Fields: map[string]string{
"Answer.field": "Field is the ref of the field answered.",
"Answer.type": "Type is the field's type. Set on a read; ignored on a write.",
"ImportIn.file": "File also files each new response in the CRM, at the time it was made.\nNothing is mailed and no webhook is told.",
"ImportIn.id": "ID is the form's id or slug, from the path.",
"ImportIn.responses": "Responses are the responses, at most 500.",
"Imported.answers": "Answers are its answers, each read against the form's field as a\nsubmission's is; a required field may be unanswered.",
"Imported.at": "At is when it was made, RFC 3339. Required.",
"Imported.email": "Email is the address it was from, when the source knew one. On a subscribe\nform the address is the response's key: one address is one subscriber,\nhowever many times and places it subscribed.",
"Imported.external": "External is its id where it was made: at most 200 characters, and the\nresponse's key, so importing it again is the same response.",
"Imported.hidden": "Hidden are values it carried, by the names the form declares.",
"Imported.source": "Source is where it was made, at most 100 characters: commerce, a list's name.",
"Imports.created": "Created counts the responses made new.",
"Imports.existing": "Existing counts the ones already held: imported before, or the same\nsubscriber.",
"Imports.failed": "Failed are the ones refused, with why.",
},
Example: json.RawMessage(`{"responses":[{"external":"sub_4XkQ","at":"2017-03-04T12:00:00Z","email":"[email protected]","source":"commerce"}],"file":true}`),
})
zip.Describe("github.com/hanzoai/form POST /v1/form/forms/:id/responses/:response/file", zip.Doc{
Description: "Files a completed response on the CRM's timeline now, and answers the response\nwith whether it is filed and, when it is not, why. A filing that failed after\nits submission is retried on a schedule; one a restart abandoned waits here.\nFiling twice is one timeline entry. 409 for an open response, or a form that\nfiles nowhere. An org admin only.",
Fields: map[string]string{
"Answer.field": "Field is the ref of the field answered.",
"Answer.type": "Type is the field's type. Set on a read; ignored on a write.",
"Respondent.email": "Email is the address the response is from: the account's, else the email\nfield's.",
"Respondent.kind": "Kind is account (a signed-in person, from their token), email (an email\nfield's answer), visitor (the page's visitor id) or none.",
"Respondent.person_id": "PersonID is the CRM person the address is: the one key a response, a list\nmembership, an email event and an experiment share. Every event and\ntimeline entry the service states carries it, never the address.",
"Respondent.subject": "Subject is the signed-in person's IAM subject.",
"Respondent.verified": "Verified is whether the respondent is who the response says: true only\nfor a signed-in person, from their token. A typed address is a claim.",
"Respondent.visitor": "Visitor is the page's visitor id.",
"Response.answers": "Answers are the answers, in the form's field order.",
"Response.completed": "Completed is whether the response was submitted whole; false is one saved\npart way.",
"Response.created": "Created is when the record was first written, RFC 3339.",
"Response.duration": "Duration is how many seconds lay between landing and submitting.",
"Response.external": "External is an imported response's id where it came from.",
"Response.filed": "Filed is whether a completed response is on the CRM's timeline. A filing\nthat failed is tried again on a schedule, and POST .../file tries it now.",
"Response.filing": "Filing is why the last filing failed; empty once it is filed.",
"Response.form": "Form is the form's id.",
"Response.hidden": "Hidden are the values the page passed in, by name.",
"Response.id": "ID is the response's id: derived from the form and the submission's token\n(from the form and the address on a subscribe form), so a retried\nsubmission is this same response.",
"Response.landed_at": "LandedAt is when the respondent opened the form, RFC 3339, as their page said.",
"Response.path": "Path is the page the form was answered on.",
"Response.respondent": "Respondent is who it is from.",
"Response.source": "Source is web, or import for a response brought in from elsewhere.",
"Response.submitted_at": "SubmittedAt is when the response was completed, RFC 3339.",
"Response.token": "Token is the submission token the response was made under.",
"Response.updated": "Updated is when it last changed, RFC 3339.",
"ResponseRef.id": "ID is the form's id or slug, from the path.",
"ResponseRef.response": "Response is the response's id, from the path.",
},
})
zip.Describe("github.com/hanzoai/form POST /v1/form/forms/:id/webhooks", zip.Doc{
Description: "Adds a webhook to a form: every completed response is posted to its https\naddress as JSON, signed with Hanzo-Signature: t=<unix seconds>,sha256=<base64\nof HMAC-SHA256(secret, \"<seconds>.\" + body)>; a receiver refuses a timestamp\nolder than five minutes and an event_id it has seen. The secret is the one\ngiven (16 to 256 characters) or one minted, kept in KMS and answered here\nonce. A form has at\nmost the platform's number of webhooks. An org admin only.",
Fields: map[string]string{
"Webhook.created": "Created is when the webhook was made, RFC 3339.",
"Webhook.enabled": "Enabled is whether responses are posted.",
"Webhook.form": "Form is the form's id.",
"Webhook.id": "ID is the webhook's id.",
"Webhook.secret": "Secret is the signing secret, answered once: when the webhook is made or\nits secret is set or rotated. Every delivery carries Hanzo-Signature:\nt=<unix seconds>,sha256=<base64 of HMAC-SHA256(secret, \"<seconds>.\" + body)>;\na receiver refuses one older than five minutes. It is kept in KMS and never\nread back.",
"Webhook.tag": "Tag names the webhook in its form. At most 64 characters.",
"Webhook.updated": "Updated is when it last changed, RFC 3339.",
"Webhook.url": "URL is the https address posted to.",
"WebhookIn.enabled": "Enabled is whether responses are posted. Default true.",
"WebhookIn.id": "ID is the form's id or slug, from the path.",
"WebhookIn.rotate": "Rotate mints a new secret on a replace, and answers it.",
"WebhookIn.secret": "Secret sets the signing secret: 16 to 256 characters. Absent on a make,\none is minted; absent on a replace, the secret held is kept.",
"WebhookIn.tag": "Tag names the webhook in its form, at most 64 characters.",
"WebhookIn.url": "URL is the https address posted to. Required.",
"WebhookIn.webhook": "Webhook is the webhook's id, from the path of a replace.",
},
Example: json.RawMessage(`{"tag":"sales","url":"https://hooks.example.com/forms"}`),
})
zip.Describe("github.com/hanzoai/form POST /v1/form/forms/:id/webhooks/:webhook/deliveries/:delivery/retry", zip.Doc{
Description: "Posts a delivery's response to its webhook again, now, and answers how it\nwent. A delivery that failed, or was waiting on a retry when the service\nrestarted, is sent this way. An org admin only.",
Fields: map[string]string{
"Delivery.attempts": "Attempts is how many posts were made.",
"Delivery.code": "Code is the last HTTP status the address answered; 0 when it did not answer.",
"Delivery.created": "Created is when the first attempt was made, RFC 3339.",
"Delivery.error": "Error is why the last attempt failed.",
"Delivery.id": "ID is the delivery's id; the body carries it as event_id.",
"Delivery.next": "Next is when the next attempt is due, RFC 3339; empty when none is.",
"Delivery.response": "Response is the response's id.",
"Delivery.status": "Status is delivered, retrying or failed.",
"Delivery.updated": "Updated is when the last was, RFC 3339.",
"Delivery.webhook": "Webhook is the webhook's id.",
"DeliveryRef.delivery": "Delivery is the delivery's id, from the path.",
"DeliveryRef.id": "ID is the form's id or slug, from the path.",
"DeliveryRef.webhook": "Webhook is the webhook's id, from the path.",
},
})
zip.Describe("github.com/hanzoai/form POST /v1/form/public/:id/responses", zip.Doc{
Description: "Answers a published form. No credential is needed.\n\nThe answers are read against the form's own fields: each names a field (by\nref) once and carries the one value its type takes, inside its bounds; a\ncompleted submission answers every required field. Hidden values are the\nnames the form declares. The response is from the signed-in person when there\nis one (their account, from their token, never from the body), else from the\nemail field's answer, else from the page's visitor id.\n\nIdempotent by token: the same token is the same response, so a submission\nsent twice files one. With completed false the answers so far are saved and\nthe response stays open; a completed response is final and a later submission\nunder its token is answered with it unchanged. A subscribe form's response is\nkeyed by its address instead: one address is one subscriber.\n\nA completed response goes to the form's sinks: the event stream, the CRM, the\nforwarding address, the welcome mail and the webhooks.\n\n429 past the platform's rate for one address, 413 past its body bound, 400\nfor a body that does not decode, a field no person fills, or any problem with\nthe answers (every one named), 404 for a form that is not published.",
Fields: map[string]string{
"Answer.field": "Field is the ref of the field answered.",
"Answer.type": "Type is the field's type. Set on a read; ignored on a write.",
"Receipt.completed": "Completed is whether the response is now submitted whole.",
"Receipt.id": "ID is the response's id.",
"Receipt.submitted_at": "SubmittedAt is when it was completed, RFC 3339.",
"Receipt.thanks": "Thanks is the form's thank-you screen, for a completed response.",
"Screen.button": "Button is the button's label. At most 64 characters.",
"Screen.description": "Description is the text under it. At most 2000 characters.",
"Screen.redirect": "Redirect is where a thank-you screen sends the respondent instead of\nshowing itself: an https address. Ignored on a welcome screen.",
"Screen.title": "Title is the screen's heading. At most 200 characters.",
"Submission.answers": "Answers are the answers, one per field at most.",
"Submission.completed": "Completed is false to save the answers so far and keep the response open\n(a later submission under the same token completes it); true or absent\nsubmits it whole, every required field answered. A completed response is\nfinal.",
"Submission.hidden": "Hidden are the values the page passes in, by the names the form declares;\neach one line of at most 500 characters.",
"Submission.id": "ID is the form's public id, from the path.",
"Submission.landed_at": "LandedAt is when the respondent opened the form, RFC 3339.",
"Submission.path": "Path is the page the form was answered on, at most 500 characters.",
"Submission.token": "Token is the client's idempotency token for this response: 8 to 64\nletters, digits, dashes and underscores. A submission sent twice under one\ntoken is one response, so a double click or a retry files nothing twice.\nAbsent, the response is new each time.",
"Submission.visitor": "Visitor is the page's visitor id: letters, digits, dot, dash and\nunderscore, at most 64. It is who the response is from when nobody is\nsigned in and no email field is answered.",
"Submission.website": "Website is a field no person sees and no person fills: a submission that\nfills it is refused.",
},
Example: json.RawMessage(`{"token":"r_9f1c2a7b","answers":[{"field":"rating","number":5},{"field":"comment","text":"Loved it"}],"hidden":{"video":"7mVTEAHHjPc"},"landed_at":"2026-11-02T08:34:10Z","visitor":"v_k3j2h1","path":"/beta"}`),
})
zip.Describe("github.com/hanzoai/form POST /v1/form/themes", zip.Doc{
Description: "Makes a theme in the caller's org: a name, four colours (#rrggbb), a font\nfamily and an https background image, each optional but the name. An org\nadmin only.",
Fields: map[string]string{
"Theme.background": "Background is an https address of an image drawn behind the form. Optional.",
"Theme.colors": "Colors are the theme's colours, each #rrggbb.",
"Theme.created": "Created is when the theme was made, RFC 3339.",
"Theme.font": "Font is the font family the form is set in: letters, digits, spaces and\ndashes, at most 64. Empty is the renderer's own.",
"Theme.id": "ID is the theme's id.",
"Theme.name": "Name is the theme's name in its org. At most 100 characters.",
"Theme.updated": "Updated is when it last changed, RFC 3339.",
},
Example: json.RawMessage(`{"name":"Hanzo dark","colors":{"question":"#ffffff","answer":"#f59e0b","button":"#ff6a00","background":"#0a0b0e"},"font":"Inter"}`),
})
zip.Describe("github.com/hanzoai/form PUT /v1/form/forms/:id", zip.Doc{
Description: "Replaces a form whole and answers it as stored. Named by a slug no form has\nyet, it makes the form under that slug, so a definition written twice is one\nform: the way a seed states a form. A field sent with its id keeps it; a type\nthe platform no longer offers stays answerable where the form already asks\nit, and is refused where it is new. An org admin only.",
Fields: map[string]string{
"CRM.company": "Company is the ref of the field whose answer is the person's company.",
"CRM.email": "Email is the ref of the field whose answer is the person's address.\nEmpty, the first email field is. A signed-in respondent is always the\naddress their account holds.",
"CRM.list": "List is the CRM list the person joins, by name (a subscribe form's\nmailing list). Empty joins none.",
"CRM.name": "Name is the ref of the field whose answer is the person's name.",
"Choice.id": "ID is the choice's id, assigned when empty.",
"Choice.label": "Label is the choice as shown. At most 200 characters.",
"Choice.ref": "Ref is how an answer names the choice; unique in the field, defaults to the id.",
"Field.choices": "Choices are what a multiple_choice or dropdown field offers, in order.",
"Field.description": "Description is the line under the question. At most 1000 characters.",
"Field.id": "ID is the field's id: assigned when a write leaves it empty, and kept\nacross edits by sending it back.",
"Field.labels": "Labels name the ends and middle of an opinion_scale.",
"Field.multiple": "Multiple is whether a multiple_choice field takes several choices.",
"Field.ref": "Ref is the field's stable name, how an answer and a sink name it:\nlowercase letters, digits, dash and underscore, at most 64, unique in the\nform. Defaults to the id.",
"Field.required": "Required is whether a completed response must answer it. A statement is\nnever required.",
"Field.start": "Start is where an opinion_scale begins: 0 (the default) or 1.",
"Field.steps": "Steps is how many points a rating (3 to 10, default 5) or an opinion_scale\n(5 to 11, default 11) has.",
"Field.title": "Title is the question as asked. At most 500 characters.",
"Field.type": "Type is one of short_text, long_text, email, phone, url, number, rating,\nopinion_scale, yes_no, multiple_choice, dropdown, date and statement.",
"Field.validations": "Validations bound an answer beyond its type.",
"Form.created": "Created is when the form was made, RFC 3339.",
"Form.fields": "Fields are the questions, in the order they are asked.",
"Form.hidden": "Hidden names the values a page passes in when it embeds the form (a video\nid, a plan): lowercase letters, digits and underscores, at most 32 each.",
"Form.id": "ID is the form's id: 15 lowercase hex characters, derived from the slug when\nthe form has one, so a slug names one form for good.",
"Form.kind": "Kind is form (every submission is a response, the default) or subscribe (a\nmailing list: an email field is required and one address is one response).",
"Form.public_id": "PublicID is the address the form is answered at: \"<org>.<slug or id>\", as\nGET /v1/form/public/{id} and POST /v1/form/public/{id}/responses take it.",
"Form.settings": "Settings is how the form is answered.",
"Form.sinks": "Sinks are where each completed response goes. Absent on a write, the\nplatform's defaults are taken.",
"Form.slug": "Slug is the form's own name within its org: lowercase letters, digits and\ndashes, at most 64. Optional; once set it is the form's id, so it cannot change.",
"Form.tags": "Tags label the form for its org: at most 20, each at most 64 characters.",
"Form.thanks": "Thanks is the screen shown after a submission, or where the respondent is\nsent. Optional.",
"Form.theme": "Theme is the id of the theme the form is drawn in. Optional.",
"Form.title": "Title is the form's name, as a respondent and the CRM timeline read it. At\nmost 200 characters.",
"Form.updated": "Updated is when it last changed, RFC 3339.",
"Form.welcome": "Welcome is the screen shown before the first question. Optional.",
"Forward.email": "Email is the address. Required.",
"Forward.name": "Name is who it is, for the greeting. Optional.",
"Options.identity": "Identity is who a response is from when nobody is signed in. claimed (the\ndefault): an address typed into an email field is the respondent's CLAIM,\nfiled on the CRM marked unverified, on the person it names only when the CRM\nalready holds them and without changing them; it joins no list and is mailed\nno welcome, and a list's consent is asked by the double opt-in instead.\nverified: only a signed-in respondent (their token) is anyone; a typed\naddress is an answer and nothing more. A signed-in respondent is verified\nunder either.",
"Options.language": "Language is the form's language, a tag like en or pt-BR. Default en.",
"Options.mode": "Mode is one (a question at a time, the default) or all (every question at once).",
"Options.progress": "Progress is whether the renderer shows a progress bar.",
"Options.visibility": "Visibility is public (answerable at its public address by anyone) or\nprivate (not served there). Default public.",
"Screen.button": "Button is the button's label. At most 64 characters.",
"Screen.description": "Description is the text under it. At most 2000 characters.",
"Screen.redirect": "Redirect is where a thank-you screen sends the respondent instead of\nshowing itself: an https address. Ignored on a welcome screen.",
"Screen.title": "Title is the screen's heading. At most 200 characters.",
"Sinks.crm": "CRM files the response on the timeline of the person it is from, or on the\norg's own timeline when it names nobody. Absent, nothing is filed.",
"Sinks.events": "Events states form_viewed, form_started and form_submitted on the\ndeployment's event stream: the form's ids and the refs of the fields\nanswered, never an answer's text.",
"Sinks.forward": "Forward mails every completed response to one address.",
"Sinks.welcome": "Welcome mails the respondent once, the first time their address answers.",
"Validations.max_length": "MaxLength is the most characters a text answer holds, at most the\nplatform's bound for the type.",
"Validations.max_value": "MaxValue is the most a number answer may be.",
"Validations.min_value": "MinValue is the least a number answer may be.",
"Welcome.body": "Body is the mail's text: plain text, a blank line a new paragraph. At most\n10000 characters.",
"Welcome.subject": "Subject is the mail's subject. At most 200 characters.",
},
})
zip.Describe("github.com/hanzoai/form PUT /v1/form/forms/:id/webhooks/:webhook", zip.Doc{
Description: "Replaces a webhook's tag, address and whether it is enabled. A secret given is\nkept in place of the one held, rotate mints a new one, and either is answered\nonce; otherwise the secret held stays. An org admin only.",
Fields: map[string]string{
"Webhook.created": "Created is when the webhook was made, RFC 3339.",
"Webhook.enabled": "Enabled is whether responses are posted.",
"Webhook.form": "Form is the form's id.",
"Webhook.id": "ID is the webhook's id.",
"Webhook.secret": "Secret is the signing secret, answered once: when the webhook is made or\nits secret is set or rotated. Every delivery carries Hanzo-Signature:\nt=<unix seconds>,sha256=<base64 of HMAC-SHA256(secret, \"<seconds>.\" + body)>;\na receiver refuses one older than five minutes. It is kept in KMS and never\nread back.",
"Webhook.tag": "Tag names the webhook in its form. At most 64 characters.",
"Webhook.updated": "Updated is when it last changed, RFC 3339.",
"Webhook.url": "URL is the https address posted to.",
"WebhookIn.enabled": "Enabled is whether responses are posted. Default true.",
"WebhookIn.id": "ID is the form's id or slug, from the path.",
"WebhookIn.rotate": "Rotate mints a new secret on a replace, and answers it.",
"WebhookIn.secret": "Secret sets the signing secret: 16 to 256 characters. Absent on a make,\none is minted; absent on a replace, the secret held is kept.",
"WebhookIn.tag": "Tag names the webhook in its form, at most 64 characters.",
"WebhookIn.url": "URL is the https address posted to. Required.",
"WebhookIn.webhook": "Webhook is the webhook's id, from the path of a replace.",
},
})
zip.Describe("github.com/hanzoai/form PUT /v1/form/themes/:id", zip.Doc{
Description: "Replaces a theme whole; every form drawn in it is drawn in the new one. An\norg admin only.",
Fields: map[string]string{
"Theme.background": "Background is an https address of an image drawn behind the form. Optional.",
"Theme.colors": "Colors are the theme's colours, each #rrggbb.",
"Theme.created": "Created is when the theme was made, RFC 3339.",
"Theme.font": "Font is the font family the form is set in: letters, digits, spaces and\ndashes, at most 64. Empty is the renderer's own.",
"Theme.id": "ID is the theme's id.",
"Theme.name": "Name is the theme's name in its org. At most 100 characters.",
"Theme.updated": "Updated is when it last changed, RFC 3339.",
},
})
}