Build on Venom Forms
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.
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
- Forms from a short outline. Send a markdown outline to
POST /forms/api/v1/forms(orforms_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(orforms_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 withGET /forms/api/v1/responses?after=<latest>, export CSV fromGET /forms/api/v1/forms/{id}/export, or add awebhookdestination and receiveforms.response.created. - Responses from your own system. A signup in your app, a lead from a partner:
POST /forms/api/v1/forms/{id}/responseswith{answers}(orforms_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(orforms_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
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
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 theformsresource (/forms/mcp) works on/forms/api/v1. - A request with an API key can send
x-venom-agent: daemon:<id>orsession:<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_requiredand each tool says where to add it.GET /forms/api/v1/mealways 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 get429withRetry-After. - Forms has no SDK keys. Respondents use the public page at
/f/{slug}or an embed of it (Share a form).
A refused write is 403 over REST, or a tool error in plain words over MCP.
Worked example
Make a feedback form that asks what went wrong after a low rating, preview a low answer, then publish it:
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:
{ "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
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.
| 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
forms_response_listandGET …/responsesreturn responses oldest first, after a cursor (after), with answers keyed by block id.fields(MCP) limits the answers to some block ids.forms_response_exportreturns CSV, at most 1000 rows a call, with the nextafterat the end.GET …/exportreturns 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_listandGET /forms/api/v1/responsesread every form's responses in one list (forms:read), newest first; each row carries its form's id, title and slug and afeedKey. To follow every form at once, passafter(thelatestof your last call): you get what was submitted since, oldest first, and a newlatest.forms_response_createandPOST …/responsessubmit a response from a backend (forms:write), with the same rules as the form's page. See Submit from a backend.
Events
1 org webhook event, generated from lib/webhooks/events.ts. Subscribe an endpoint to them in Settings, Webhooks (see Webhooks and events).
| 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.
REST routes
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
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.