# List forms URL: https://docs.hanzo.ai/docs/openapi/form/list-forms > Lists the caller org's forms, newest first, a page at a time; search keeps the forms whose title holds it and tag the ones carrying it. `GET /v1/form/forms` > [Form →](https://docs.hanzo.ai/docs/openapi/form) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | -------------------------------------- | | **Address** | `https://api.hanzo.ai/v1/form/forms` | | **Method** | `GET` | | **Operation** | `list_forms` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | Lists the caller org's forms, newest first, a page at a time; search keeps the forms whose title holds it and tag the ones carrying it. An org admin only. ## Request 4 fields. | Field | In | Type | Required | Description | | ----------- | ----- | ------- | -------- | ----------------------------------------------------------- | | `page` | query | integer | — | Page is the page, from 1. | | `page_size` | query | integer | — | PageSize is how many a page holds: at most 200, default 50. | | `search` | query | string | — | Search keeps the forms whose title holds it. | | `tag` | query | string | — | Tag keeps the forms tagged with it. | ## Response | Status | Body | Meaning | | --------- | --------------- | ------- | | `200` | form.FormList | ok | | `default` | problem-details | refused | `200` body — 65 fields. | Field | In | Type | Always | Description | | ----------------------------------------- | ---- | ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `items` | body | form.Form\[] | — | Items are the forms, newest first. | | `items[].created` | body | string | — | Created is when the form was made, RFC 3339. | | `items[].fields` | body | form.Field\[] | — | Fields are the questions, in the order they are asked. | | `items[].fields[].choices` | body | form.Choice\[] | — | Choices are what a multiple\_choice or dropdown field offers, in order. | | `items[].fields[].choices[].id` | body | string | — | ID is the choice's id, assigned when empty. | | `items[].fields[].choices[].label` | body | string | — | Label is the choice as shown. | | `items[].fields[].choices[].ref` | body | string | — | Ref is how an answer names the choice; unique in the field, defaults to the id. | | `items[].fields[].description` | body | string | — | Description is the line under the question. | | `items[].fields[].id` | body | string | — | ID is the field's id: assigned when a write leaves it empty, and kept across edits by sending it back. | | `items[].fields[].labels` | body | form.Labels | — | | | `items[].fields[].labels.center` | body | string | — | | | `items[].fields[].labels.left` | body | string | — | | | `items[].fields[].labels.right` | body | string | — | | | `items[].fields[].multiple` | body | boolean | — | Multiple is whether a multiple\_choice field takes several choices. | | `items[].fields[].ref` | body | string | — | Ref is the field's stable name, how an answer and a sink name it: lowercase letters, digits, dash and underscore, at most 64, unique in the form. | | `items[].fields[].required` | body | boolean | — | Required is whether a completed response must answer it. | | `items[].fields[].start` | body | integer (int64) | — | Start is where an opinion\_scale begins: 0 (the default) or 1. | | `items[].fields[].steps` | body | integer (int64) | — | Steps is how many points a rating (3 to 10, default 5) or an opinion\_scale (5 to 11, default 11) has. | | `items[].fields[].title` | body | string | — | Title is the question as asked. | | `items[].fields[].type` | body | string | — | Type is one of short\_text, long\_text, email, phone, url, number, rating, opinion\_scale, yes\_no, multiple\_choice, dropdown, date and statement. | | `items[].fields[].validations` | body | form.Validations | — | | | `items[].fields[].validations.max_length` | body | integer (int64) | — | MaxLength is the most characters a text answer holds, at most the platform's bound for the type. | | `items[].fields[].validations.max_value` | body | number (double) | — | MaxValue is the most a number answer may be. | | `items[].fields[].validations.min_value` | body | number (double) | — | MinValue is the least a number answer may be. | | `items[].hidden` | body | string\[] | — | Hidden names the values a page passes in when it embeds the form (a video id, a plan): lowercase letters, digits and underscores, at most 32 each. | | `items[].id` | body | string | — | ID is the form's id: 15 lowercase hex characters, derived from the slug when the form has one, so a slug names one form for good. | | `items[].kind` | body | string | — | Kind is form (every submission is a response, the default) or subscribe (a mailing list: an email field is required and one address is one response). | | `items[].public_id` | body | string | — | PublicID is the address the form is answered at: "\.\", as GET /v1/form/public/{id} and POST /v1/form/public/{id}/responses take it. | | `items[].settings` | body | form.Options | — | | | `items[].settings.identity` | body | string | — | Identity is who a response is from when nobody is signed in. | | `items[].settings.language` | body | string | — | Language is the form's language, a tag like en or pt-BR. | | `items[].settings.mode` | body | string | — | Mode is one (a question at a time, the default) or all (every question at once). | | `items[].settings.progress` | body | boolean | — | Progress is whether the renderer shows a progress bar. | | `items[].settings.visibility` | body | string | — | Visibility is public (answerable at its public address by anyone) or private (not served there). | | `items[].sinks` | body | form.Sinks | — | | | `items[].sinks.crm` | body | form.CRM | — | | | `items[].sinks.crm.company` | body | string | — | Company is the ref of the field whose answer is the person's company. | | `items[].sinks.crm.email` | body | string | — | Email is the ref of the field whose answer is the person's address. | | `items[].sinks.crm.list` | body | string | — | List is the CRM list the person joins, by name (a subscribe form's mailing list). | | `items[].sinks.crm.name` | body | string | — | Name is the ref of the field whose answer is the person's name. | | `items[].sinks.events` | body | boolean | — | Events states form\_viewed, form\_started and form\_submitted on the deployment's event stream: the form's ids and the refs of the fields answered, never an answer's text. | | `items[].sinks.forward` | body | form.Forward | — | | | `items[].sinks.forward.email` | body | string | — | Email is the address. | | `items[].sinks.forward.name` | body | string | — | Name is who it is, for the greeting. | | `items[].sinks.welcome` | body | form.Welcome | — | | | `items[].sinks.welcome.body` | body | string | — | Body is the mail's text: plain text, a blank line a new paragraph. | | `items[].sinks.welcome.subject` | body | string | — | Subject is the mail's subject. | | `items[].slug` | body | string | — | Slug is the form's own name within its org: lowercase letters, digits and dashes, at most 64. | | `items[].tags` | body | string\[] | — | Tags label the form for its org: at most 20, each at most 64 characters. | | `items[].thanks` | body | form.Screen | — | | | `items[].thanks.button` | body | string | — | Button is the button's label. | | `items[].thanks.description` | body | string | — | Description is the text under it. | | `items[].thanks.redirect` | body | string | — | Redirect is where a thank-you screen sends the respondent instead of showing itself: an https address. | | `items[].thanks.title` | body | string | — | Title is the screen's heading. | | `items[].theme` | body | string | — | Theme is the id of the theme the form is drawn in. | | `items[].title` | body | string | — | Title is the form's name, as a respondent and the CRM timeline read it. | | `items[].updated` | body | string | — | Updated is when it last changed, RFC 3339. | | `items[].welcome` | body | form.Screen | — | | | `items[].welcome.button` | body | string | — | Button is the button's label. | | `items[].welcome.description` | body | string | — | Description is the text under it. | | `items[].welcome.redirect` | body | string | — | Redirect is where a thank-you screen sends the respondent instead of showing itself: an https address. | | `items[].welcome.title` | body | string | — | Title is the screen's heading. | | `page` | body | integer (int64) | — | Page is this page, from 1. | | `page_size` | body | integer (int64) | — | PageSize is how many a page holds. | | `total` | body | integer (int64) | — | Total is how many forms answer the query. | Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** ```bash hanzo form forms list ``` **SDK** **.ts** ```ts import { Configuration, FormApi } from 'hanzoai'; const api = new FormApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.listForms(); ``` **.py** ```python from hanzoai.cloud import ApiClient, Configuration from hanzoai.cloud.api import FormApi client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"])) result = FormApi(client).list_forms() ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.FormAPI.ListForms(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust use hanzo_client::apis::{configuration::Configuration, form_api}; let mut cfg = Configuration::new(); cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok(); let result = form_api::list_forms(&cfg, Default::default()).await?; ``` **.java** ```java import ai.hanzo.cloud.ApiClient; import ai.hanzo.cloud.api.FormApi; ApiClient client = new ApiClient(); client.setBearerToken(System.getenv("HANZO_API_KEY")); var result = new FormApi(client).listForms(); ``` The method above is the one at the current release of the document. `hanzoai@8.5.914` (npm) and `hanzoai@8.5.914` (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. [SDKs →](https://docs.hanzo.ai/docs/sdks) **HTTP** ```bash curl https://api.hanzo.ai/v1/form/forms \ -H "Authorization: Bearer $HANZO_API_KEY" ``` **MCP** Tool `form`, op `list_forms` — POST the JSON-RPC envelope to `https://api.hanzo.ai/v1/mcp`. ```bash curl -X POST https://api.hanzo.ai/v1/mcp \ -H "Authorization: Bearer $HANZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "form", "arguments": { "op": "list_forms", "input": {} } } }' ``` --- [Form API](https://docs.hanzo.ai/docs/openapi/form) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)