A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Typeform API is how an app or AI agent works with a Typeform account: building a form from a definition, reading the responses a form has collected, registering a webhook to receive new submissions, and managing images, themes, and workspaces. Access is granted through a bearer token, either an OAuth token carrying granular scopes or a personal access token, and an agent is limited to the areas and direction those scopes allow. There is no version to pin, and Typeform can push each submission to a webhook the moment a form is completed.
How an app or AI agent connects to Typeform determines what it can reach. There is a route for building forms and reading data, a route for receiving submission events, and a hosted server that exposes Typeform tools to agents, each governed by the token behind it and the permissions that token carries.
The REST API answers at https://api.typeform.com and returns JSON. Accounts on the EU Data Center call https://api.eu.typeform.com instead. It covers the Create, Responses, and Webhooks APIs, and a call authenticates with a bearer access token.
Typeform POSTs a form_response payload to a registered URL the moment a form is submitted. The receiver verifies the Typeform-Signature header, an HMAC SHA-256 of the raw body keyed with the webhook secret and base64-encoded with a sha256= prefix, to confirm the request came from Typeform. New webhook URLs must use HTTPS.
Typeform's first-party MCP server lets an agent call Typeform through the Model Context Protocol at https://api.typeform.com/mcp, with https://api.eu.typeform.com/mcp for EU accounts. It is in beta with a limited tool set covering reading forms, managing contacts, and workspaces, and currently authenticates with a personal access token as a bearer token; OAuth is planned.
An OAuth 2.0 application requests each user's permission for a set of scopes, then receives an access token that acts on that user's behalf. Scopes are granular per area and direction, such as forms:read, forms:write, responses:read, responses:write, and webhooks:write. Adding the offline scope returns a refresh token for continued access.
A personal access token authenticates as a single account without an OAuth flow, sent as a bearer token. It is the quickest way to call the API for one account's own data, and is currently the only way to authenticate with the MCP server.
The Typeform API is split into areas an agent can act on, like forms, responses, webhooks, images and themes, and workspaces. Each area has its own methods and its own permission, and some reach far more than others, such as reading every response a form has collected.
List, read, create, update, and delete forms, and read and update their custom screen messages.
Retrieve the submissions a form has collected, and delete responses by id.
List a form's webhooks, read a single webhook, create or update one, and delete it.
List and add account images, and list, create, and delete the themes that style forms.
List, create, read, and delete workspaces, and read the authenticated account's basic profile.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
FormsList, read, create, update, and delete forms, and read and update their custom screen messages.8 | ||||||
| GET | /forms | List the forms in the account, with paging, search, and workspace filtering. | read | forms:read | Current | |
Returns a list of forms. page_size defaults to 10 and tops out at 200. Acts onform Permission (capability) forms:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /forms | Create a new form from a JSON definition. | write | forms:write | Current | |
The full form definition, fields, logic, theme, and settings, is sent in the request body. Acts onform Permission (capability) forms:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /forms/{form_id} | Retrieve a single form's full definition. | read | forms:read | Current | |
Read-only. Acts onform Permission (capability) forms:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /forms/{form_id} | Replace a form's entire definition. | write | forms:write | Current | |
A whole-definition update; the body replaces the existing form. Acts onform Permission (capability) forms:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /forms/{form_id} | Apply a partial update to a form using JSON Patch operations. | write | forms:write | Current | |
Takes a JSON Patch array, so individual fields can change without resending the whole form. Acts onform Permission (capability) forms:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /forms/{form_id} | Delete a form. | write | forms:write | Current | |
Removes the form and its configuration. Acts onform Permission (capability) forms:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /forms/{form_id}/messages | Retrieve a form's custom screen messages. | read | forms:read | Current | |
Returns the customizable text shown on a form, such as button labels and screens. Acts onform message Permission (capability) forms:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /forms/{form_id}/messages | Update a form's custom screen messages. | write | forms:write | Current | |
Replaces the customizable message text on the form. Acts onform message Permission (capability) forms:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ResponsesRetrieve the submissions a form has collected, and delete responses by id.2 | ||||||
| GET | /forms/{form_id}/responses | Retrieve the responses a form has collected, with date filters and paging. | read | responses:read | Current | |
Returns respondent answers. page_size defaults to 25 and tops out at 1000. Very recent submissions, within roughly the last 30 minutes, may not appear yet. Acts onresponse Permission (capability) responses:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /forms/{form_id}/responses | Delete responses to a form by id. | write | responses:write | Current | |
The included_response_ids parameter lists up to 1000 response ids. A 200 confirms the deletion was registered, not that it finished immediately. Acts onresponse Permission (capability) responses:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList a form's webhooks, read a single webhook, create or update one, and delete it.4 | ||||||
| GET | /forms/{form_id}/webhooks | List all webhooks configured on a form. | read | webhooks:read | Current | |
Read-only. Acts onwebhook Permission (capability) webhooks:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /forms/{form_id}/webhooks/{tag} | Retrieve a single webhook by its tag. | read | webhooks:read | Current | |
The tag is the chosen name for the webhook on that form. Acts onwebhook Permission (capability) webhooks:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /forms/{form_id}/webhooks/{tag} | Create a webhook on a form, or update the existing one for that tag. | write | webhooks:write | Current | |
Sets the destination URL, the enabled flag, and the secret used to sign deliveries. The same call both creates and updates. Acts onwebhook Permission (capability) webhooks:writeVersionAvailable since the API’s base version Webhook event form_responseRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /forms/{form_id}/webhooks/{tag} | Delete a webhook from a form. | write | webhooks:write | Current | |
Stops further deliveries for that tag. Acts onwebhook Permission (capability) webhooks:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Images & themesList and add account images, and list, create, and delete the themes that style forms.5 | ||||||
| GET | /images | Retrieve the JSON descriptions of all images in the account. | read | images:read | Current | |
Read-only. Acts onimage Permission (capability) images:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /images | Add an image to the account for use in forms. | write | images:write | Current | |
The image is sent base64-encoded or by URL in the request body. Acts onimage Permission (capability) images:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /themes | Retrieve the JSON descriptions of all themes in the account. | read | themes:read | Current | |
Read-only. Acts ontheme Permission (capability) themes:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /themes | Create a theme that styles a form's colors, fonts, and background. | write | themes:write | Current | |
A core styling write. Acts ontheme Permission (capability) themes:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /themes/{theme_id} | Delete a theme. | write | themes:write | Current | |
Removes the theme from the account. Acts ontheme Permission (capability) themes:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Workspaces & accountList, create, read, and delete workspaces, and read the authenticated account's basic profile.5 | ||||||
| GET | /workspaces | Retrieve all workspaces the account has access to. | read | workspaces:read | Current | |
page_size defaults to 10 and tops out at 200. Acts onworkspace Permission (capability) workspaces:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /workspaces | Create a workspace. | write | workspaces:write | Current | |
A workspace groups forms together. Acts onworkspace Permission (capability) workspaces:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspace_id} | Retrieve a single workspace. | read | workspaces:read | Current | |
Read-only. Acts onworkspace Permission (capability) workspaces:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /workspaces/{workspace_id} | Delete a workspace. | write | workspaces:write | Current | |
Deleting a workspace also affects the forms inside it. Acts onworkspace Permission (capability) workspaces:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /me | Retrieve the authenticated account's alias, email address, and language. | read | accounts:read | Current | |
Returns only the token owner's own profile; there is no endpoint to list all users in an account. Acts onaccount Permission (capability) accounts:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Typeform can notify an app or AI agent the moment a form is submitted, instead of the app repeatedly asking. It posts the submission payload to a webhook URL registered on the form, and a signature header lets the receiver confirm the payload came from Typeform.
| Event | What it signals | Triggered by |
|---|---|---|
form_response | Fires when a form is submitted, delivering the respondent's answers, the form definition, and landing and submission timestamps. This is the single event the Webhooks API delivers. | /forms/{form_id}/webhooks/{tag} |
Typeform limits how fast an app or AI agent can call, by a request rate measured per second and per Typeform account, with separate ceilings on how many forms and responses a single response query returns.
Typeform allows two requests per second, per Typeform account, for the Create and Responses APIs. Going over returns HTTP 429, so an integration that batches form edits or pulls large response sets should pace its calls rather than send them in a burst. The limit is per account, so several agents sharing one account's token share the same two-per-second budget.
List endpoints page through results with the page and page_size parameters. For forms and workspaces, page_size defaults to 10 and reaches a maximum of 200. The Responses endpoint pages differently, defaulting to 25 responses with a maximum page_size of 1000, and it also supports cursor-style before and after parameters and since and until date filters.
A single Responses request returns at most 1000 responses, and a forms or workspaces list returns at most 200 items per page. A delete-responses request can name up to 1000 response ids at once.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed, such as an invalid form definition, a bad JSON Patch operation, or an invalid query parameter. | Read the error message, correct the request body or parameters, and resend. |
| 401 | Unauthorized | The access token is missing, invalid, or expired. | Send a valid bearer token in the Authorization header, refreshing the OAuth token if it has expired. |
| 403 | Forbidden | The token is valid but lacks the scope the call needs, or the account does not have access to the resource. | Grant the missing scope, such as responses:read or forms:write, and reconnect. |
| 404 | Not Found | The form, response, webhook, theme, or workspace does not exist, or the token cannot see it. | Confirm the id in the path and that the token has access to it. |
| 429 | Too Many Requests | The request rate of two per second per account was exceeded. | Slow the request rate and retry after a short pause. |
Typeform's API is not versioned by a number or date in the path. There is a single, continuously updated API, and notable changes are published as a dated changelog.
Typeform's API has no version number or date in the request path. It is a single, continuously updated API, and notable changes, including breaking ones, are published as a dated changelog rather than as new versions. An integration tracks that changelog rather than pinning a version. The dated entries below are recent changes from that changelog, newest first.
All new webhook URLs must use HTTPS. Existing HTTP webhooks keep working but cannot be repointed to another HTTP URL, and the verify_ssl parameter became read-only.
The Translations API documentation was corrected: the properties.labels field is a plain object, not an array.
The undocumented settings.capabilities field was removed from form definitions as part of cleanup work.
Added the ability to configure an enrichment form setting through the API for eligible accounts.
The Create API added the ability to define milestones within form definitions, and the Responses API added a query parameter to retrieve partial responses.
There is no version to pin; an integration tracks the dated changelog for breaking changes.
Typeform API changelog ↗Bollard AI sits between a team's AI agents and Typeform. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.