---
title: Build on Venom Forms
description: Build, preview, publish and close forms from code or an agent, read and export their responses, and send each response to Notes, Tasks, Slack, Funnel, Support, Calendar or your own webhook, over REST or MCP.
section: developers
order: 120
audience: [builder, agent]
sources: [services/nodejs-cloud/lib/forms/mcp, services/nodejs-cloud/lib/forms/auth.ts, services/nodejs-cloud/lib/forms/access.ts, services/nodejs-cloud/lib/forms/http.ts, services/nodejs-cloud/lib/forms/destinations, services/nodejs-cloud/app/forms/api, services/nodejs-cloud/app/forms/mcp/route.ts, services/nodejs-cloud/contracts/forms-openapi.yaml, docs/adr/0056-venom-forms.md]
features: [cloud.forms]
---

Venom Forms builds forms out of blocks (questions and statements) with stable ids, logic rules and settings. An agent
or a script can take a form from an outline to a published link, preview the path some answers take through the logic,
and read the responses later. Everything the builder does is a REST operation under `/forms/api/v1` and an MCP tool.
Every change is recorded with the caller's name in the form's history, and any change can be reverted.

## What you can build {#build}

- **Forms from a short outline.** Send a markdown outline to `POST /forms/api/v1/forms` (or `forms_form_create`) and get a draft with block ids back.
- **A check before publishing.** Run sample answers through the logic with `POST /forms/api/v1/forms/{id}/preview` (or `forms_form_preview`); nothing is stored.
- **Responses into your own system.** Page through `GET /forms/api/v1/forms/{id}/responses?after=<cursor>`, follow every form at once with `GET /forms/api/v1/responses?after=<latest>`, export CSV from `GET /forms/api/v1/forms/{id}/export`, or add a `webhook` destination and receive `forms.response.created`.
- **Responses from your own system.** A signup in your app, a lead from a partner: `POST /forms/api/v1/forms/{id}/responses` with `{answers}` (or `forms_response_create`) stores it as a response, validated and delivered like one from the form's page.
- **Lead and support intake.** Connect a form to a Funnel deal, a Support conversation or a Tasks team's Triage with `forms_form_connect`, so each response becomes a record there.
- **A weekly summary.** Read counts, completion, choice shares, averages, NPS and drop-off from `GET /forms/api/v1/forms/{id}/summary` (or `forms_response_summary`) and post them where your team reads.
- **Delivery monitoring.** Read the delivery log (`forms_delivery_list`) and send failed ones again (`forms_delivery_retry`).

## At a glance {#glance}

Generated from the code on every docs build.

| | |
|---|---|
| MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/forms`, server name `venom-forms` |
| Connect | `claude mcp add --transport http venom-forms https://cloud.usevenom.dev/workspace/mcp/forms` |
| MCP tools | 19 (9 read, 10 write) |
| OAuth scopes | `forms:read` `forms:write` |
| REST twin | none yet |
| Forms API | 23 operations |
| Webhook events | `forms.response.created` |

The older endpoint `/forms/mcp` still serves the same tools. `/forms/agents` in the app shows the connect commands
with your origin filled in.

## Authentication and scopes {#scopes}

Forms has two permissions, `forms:read` and `forms:write`, and no admin permission.

| Credential | Recorded as | Permissions |
|---|---|---|
| Personal API key (`vck_…`) | the key's name, `key:<key id>` | the member's role: owners, admins and developers read and write; billing and viewer members read |
| Team API key | the key's name, `key:<key id>` | `forms:read` and `forms:write` |
| OAuth app | the app's name, `mcp:<client id>:<member>` | the member's role, narrowed to the scopes the member granted |

- An OAuth token works only on the resource it was issued for: a token for `/workspace/mcp` (or
  `/workspace/mcp/forms`) works on those endpoints, and only a token for the `forms` resource (`/forms/mcp`) works on
  `/forms/api/v1`.
- A request with an API key can send `x-venom-agent: daemon:<id>` or `session:<id>` to record one of the org's daemons
  or venom sessions as the actor. It grants nothing beyond the key's own rights.
- If the org has not added Forms, each REST call answers `403 addon_required` and each tool says where to add it.
  `GET /forms/api/v1/me` always answers, with your permissions.
- Rate limits per credential: 600 requests a minute on `/forms/api/v1`, 240 a minute on `/forms/mcp`. Past the limit
  you get `429` with `Retry-After`.
- Forms has no SDK keys. Respondents use the public page at `/f/{slug}` or an embed of it
  ([Share a form](/docs/cloud/forms-sharing.md)).

A refused write is `403` over REST, or a tool error in plain words over MCP.

## Worked example {#example}

Make a feedback form that asks what went wrong after a low rating, preview a low answer, then publish it:

```bash
curl -X POST "$VENOM_CLOUD/forms/api/v1/forms" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"outline": "# Feedback\n- Rating [rating 1-5] *\n- What went wrong? [long text]\nif Rating <= 2 then show What went wrong?"}'

curl -X POST "$VENOM_CLOUD/forms/api/v1/forms/frm_…/preview" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"answers": {"<rating-block-id>": 1}}'

curl -X PATCH "$VENOM_CLOUD/forms/api/v1/forms/frm_…" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' -H 'If-Match: "1"' \
  -d '{"instructions": [{"kind": "publish"}], "comment": "ready for the beta list"}'
```

The create answer has the form's id, its block ids and any outline line it could not read (`warnings`). A new form is
at version 1; each answer's `ETag` is the current version, which the next write sends back as `If-Match`.

The same create over MCP, from any client connected to `/workspace/mcp/forms`:

```json
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "forms_form_create",
              "arguments": { "outline": "# Feedback\n- Rating [rating 1-5] *\n- What went wrong? [long text]\nif Rating <= 2 then show What went wrong?" } } }
```

Then `forms_form_preview` with `{"form": "frm_…", "answers": {"<rating-block-id>": 1}}` and `forms_form_publish` with
`{"form": "frm_…", "expectVersion": 1}`. Tools take the form's id or its slug as `form`.

## Changing a form {#instructions}

`forms_form_update` and `PATCH /forms/api/v1/forms/{id}` take a list of instructions that address blocks and rules by
id, applied in order, all or none, and only if the form is still at the version you read. The kinds are `addBlock`,
`updateBlock`, `moveBlock`, `removeBlock`, `addRule`, `updateRule`, `removeRule`, `reorderRules`, `setTitle`,
`setSettings`, `publish` and `close`. The full shapes are in the tool's description and in
`contracts/forms-openapi.yaml`; the outline syntax and rule semantics are on
[Forms logic, outlines and instructions](/docs/cloud/forms-logic.md).

| Option | REST | MCP | What it does |
|---|---|---|---|
| Version check | `If-Match: "<version>"` or `expectVersion` | `expectVersion` | `409 version_conflict` if the form moved: read it again |
| Idempotency | `Idempotency-Key` | `idempotencyKey` | a retry within 24 hours returns the first answer |
| Dry run | `dryRun: true` | `dryRun: true` | validates and shows the diff without saving |
| Comment | `comment` | `comment` | shown in the history |

A bad instruction is `422 invalid_instruction` and names its index and the reason. `forms_form_history` (or
`GET …/history`) lists changes with audit ids, and `forms_form_revert` (or `POST …/history` with `auditId`) puts the
form back as it was before one.

Deleting is for good: `forms_form_delete` needs `confirm` set to the form's id or slug, and `forms_response_delete`
needs `confirm: "delete"` (up to 50 responses a call). Both are audited without the content.

## Responses and exports {#responses}

- `forms_response_list` and `GET …/responses` return responses oldest first, after a cursor (`after`), with answers
  keyed by block id. `fields` (MCP) limits the answers to some block ids.
- `forms_response_export` returns CSV, at most 1000 rows a call, with the next `after` at the end.
  `GET …/export` returns up to 50 000 rows in one file. Text that starts with `=`, `+`, `-` or `@` is written with a
  leading apostrophe.
- `GET …/files/{fid}` downloads a file a respondent uploaded (`forms:read`).
- `forms_feed_list` and `GET /forms/api/v1/responses` read every form's responses in one list (`forms:read`), newest
  first; each row carries its form's id, title and slug and a `feedKey`. To follow every form at once, pass `after`
  (the `latest` of your last call): you get what was submitted since, oldest first, and a new `latest`.
- `forms_response_create` and `POST …/responses` submit a response from a backend (`forms:write`), with the same rules
  as the form's page. See [Submit from a backend](/docs/cloud/forms-responses.md#submit-from-a-backend).

## Events {#events}

1 org webhook event, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)).

| Event | When |
|---|---|
| `forms.response.created` | A response was submitted to a published Venom Forms form: its id, the form and the time. The answers are included only when the form's "include answers" setting is on (they can be personal data). |

`forms.response.created` is sent only for forms with a `webhook` destination. Its data has `form_id`, `form_title`,
`response_id`, `version` and `submitted_at`; `answers` and `hidden` are added only when the form's `includeAnswers`
setting is on.

Each form also has destinations: where its responses are delivered after they are saved. Add them with
`forms_form_connect` (`op: "add"`, a `kind` and a `config`), or over REST in `setSettings` (`settings.destinations`, a
list of `{id, kind, on, config}`, up to 20). `GET /forms/api/v1/connect` lists what each kind can point at.

| Kind | What a response becomes |
|---|---|
| `globe` | a row in a Notes database in the org vault, questions matched to properties by name (`createDatabase: true` makes one) |
| `tasks` | an issue in a Tasks team's Triage, titled from a template |
| `webhook` | a `forms.response.created` event to every org webhook endpoint that takes it |
| `slack` | a message in a channel, through the org's own Slack app |
| `funnel_deal` | a People person made or matched from the contact answers, and a Funnel deal for them in a pipeline |
| `support_conversation` | a Venom Support conversation, with the answers as the first message |
| `calendar_booking` | a routing step: on submit the respondent books the matching Calendar event type |

Delivery is at least once per response and destination. Each is tried at once, then after 1 minute, 5 minutes,
30 minutes and 2 hours, and marked failed after the fifth failure. `forms_delivery_list` and `GET …/deliveries` show
the log (state, attempts, last error, what was made); `forms_delivery_retry` and `POST …/deliveries/{did}/retry` send
one again. Webhook and Slack deliveries carry answers only when `includeAnswers` is on. See
[Send form responses](/docs/cloud/forms-destinations.md).

## REST routes {#rest}

The Forms API: 23 operations, generated from `services/nodejs-cloud/contracts/forms-openapi.yaml`. "Key or token" is a Venom API key or an OAuth access token; SDK keys and client ids belong to an environment and are for your app's runtime.

**/me**

| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | `/forms/api/v1/me` | Who is calling and their permissions (never gated on the add-on). | key or token |

**/forms**

| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | `/forms/api/v1/forms` |  | key or token |
| POST | `/forms/api/v1/forms` |  | key or token |
| GET | `/forms/api/v1/forms/{id}` |  | key or token |
| PATCH | `/forms/api/v1/forms/{id}` |  | key or token |
| DELETE | `/forms/api/v1/forms/{id}` |  | key or token |
| POST | `/forms/api/v1/forms/{id}/preview` | The path these answers take through the form's logic, and what validation says. Nothing is stored. | key or token |
| GET | `/forms/api/v1/forms/{id}/responses` |  | key or token |
| POST | `/forms/api/v1/forms/{id}/responses` | Submit a response from a backend (forms:write): the published version's validation, closed, ended and full forms refused (409 closed, ended, full, not_published), rate limited per credential and per form (429), delivered to every destination. File questions cannot be answered this way. Recorded as submitted by the credential (a response.submit entry in the history). | key or token |
| GET | `/forms/api/v1/forms/{id}/summary` |  | key or token |
| GET | `/forms/api/v1/forms/{id}/history` |  | key or token |
| POST | `/forms/api/v1/forms/{id}/history` | Put back the form as it was before an audit entry. | key or token |
| DELETE | `/forms/api/v1/forms/{id}/responses/{rid}` | Delete one response and its files (forms:write). | key or token |
| GET | `/forms/api/v1/forms/{id}/export` | The responses as CSV (up to 50 000; text starting with = + - @ is written with a leading apostrophe). | key or token |
| GET | `/forms/api/v1/forms/{id}/files/{fid}` | A file a respondent uploaded, as a download (forms:read). | key or token |
| POST | `/forms/api/v1/forms/{id}/logo` | Upload the form's logo: the raw image as the body (PNG, JPEG, WebP or GIF, up to 512 KB). Returns the file id for setSettings theme.logoFileId. | key or token |
| GET | `/forms/api/v1/forms/{id}/deliveries` | The delivery log: one row per response and destination, newest first. | key or token |
| POST | `/forms/api/v1/forms/{id}/deliveries/{did}/retry` | Send a failed or finished delivery again (forms:write). | key or token |
| POST | `/forms/api/v1/forms/{id}/connect/database` | Create a Notes database in the org vault with a property per question; returns the mapping for a Notes destination. | key or token |
| POST | `/forms/api/v1/forms/{id}/connect/match` | A mapping of the form's questions to an existing database's properties, matched by name. | key or token |

**/responses**

| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | `/forms/api/v1/responses` | Every form's responses (forms:read): newest first, paged back with before; or after a feedKey, oldest first, to follow every form at once. latest is the feedKey to pass as after on the next poll. | key or token |

**/draft**

| Method | Path | Summary | Auth |
|---|---|---|---|
| POST | `/forms/api/v1/draft` | Draft with AI: a prompt in, a markdown outline out, through the organisation's own gear under its daily AI cap. Nothing is stored; POST /forms/api/v1/forms creates from the outline. | key or token |

**/connect**

| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | `/forms/api/v1/connect` | What a destination can be pointed at: the org vault's databases, Tasks teams with their Triage, whether Slack is connected, how many webhook endpoints take forms.response.created. | key or token |

## MCP tools {#tools}

19 tools: 9 read, 10 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP.

| Tool | Title | Access | Scope | REST route |
|---|---|---|---|---|
| `forms_delivery_list` | List deliveries | read | `forms:read` |  |
| `forms_delivery_retry` | Retry deliveries | write | `forms:write` |  |
| `forms_feed_list` | Follow every form's responses | read | `forms:read` |  |
| `forms_form_close` | Close a form | write (destructive) | `forms:write` |  |
| `forms_form_connect` | Send responses somewhere | write | `forms:write` |  |
| `forms_form_create` | Create a form | write | `forms:write` |  |
| `forms_form_delete` | Delete a form | write (destructive) | `forms:write` |  |
| `forms_form_get` | Get a form | read | `forms:read` |  |
| `forms_form_history` | A form's change history | read | `forms:read` |  |
| `forms_form_list` | List forms | read | `forms:read` |  |
| `forms_form_preview` | Preview the path through a form | read | `forms:read` |  |
| `forms_form_publish` | Publish a form | write | `forms:write` |  |
| `forms_form_revert` | Revert a change | write (destructive) | `forms:write` |  |
| `forms_form_update` | Change a form | write | `forms:write` |  |
| `forms_response_create` | Submit a response | write | `forms:write` |  |
| `forms_response_delete` | Delete responses | write (destructive) | `forms:write` |  |
| `forms_response_export` | Export responses as CSV | read | `forms:read` |  |
| `forms_response_list` | Read responses | read | `forms:read` |  |
| `forms_response_summary` | Summarise responses | read | `forms:read` |  |

Reads answer as compact markdown, or JSON with `format: "json"`. The tool list is the same for every caller; a
read-only credential gets a plain-words refusal when it calls a write tool.

## Related {#related}

- [Venom Forms](/docs/cloud/forms.md): the builder.
- [Forms logic, outlines and instructions](/docs/cloud/forms-logic.md), [Share a form and take responses](/docs/cloud/forms-sharing.md), [Form responses](/docs/cloud/forms-responses.md) and [Send form responses](/docs/cloud/forms-destinations.md).
- [Authentication and scopes](/docs/developers/auth.md), [Errors, limits and pagination](/docs/developers/conventions.md), [Webhooks and events](/docs/developers/webhooks.md) and [MCP](/docs/developers/mcp.md).
