Skip to content
Docs menu

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.

View .md

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 (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

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 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).

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_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.

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.