Public form API - Hive Documentation

A workflow with a Public form trigger can be submitted without a Hive account. The Hive-hosted form page uses two unauthenticated endpoints, and you can call them yourself — from a server, a script or an automation tool — to start a workflow run from another system.

This is the supported way to start a Hive workflow from outside Hive. Workflows have no webhook trigger, and Hive has no customer API keys. To send events into Signals instead, use an incoming webhook.

Before you start

Build a workflow with a Public form trigger and deploy it.
Select Form link, then Create form link, and copy the link. It looks like https://<your Hive app>/forms?token=<token>.
The value of token (20-200 characters) is the credential. Anyone who holds it can submit the form, so treat it like a password and keep it out of client-side code.

The token stops working when a new link is created, the workflow is redeployed, re-activated, paused, returned to draft or deleted, or its owner can no longer run it. See when a link stops working. The endpoints below live on your Hive API host, under /public/workflow-forms. In these examples it is written https://<your Hive API host>; ask Hive support for the address if you do not have it.

The API only accepts cross-origin browser requests from Hive’s own app. Call it from a server, not from JavaScript in a visitor’s browser on your site.

Read a form

GET /public/workflow-forms/forms?token=<token> Returns only what a visitor needs to fill the form in — never the workflow behind it.

curl "https://<your Hive API host>/public/workflow-forms/forms?token=$FORM_TOKEN"

200 OK

{
  "title": "Request a callback",
  "description": "We will call you within one working day.",
  "confirmationMessage": "Thanks — we have your request.",
  "fields": [
    { "key": "full_name", "label": "Full name", "type": "text", "required": true },
    { "key": "email", "label": "Email", "type": "email", "required": true },
    { "key": "details", "label": "What do you need?", "type": "textarea", "required": false },
    { "key": "consent", "label": "I agree to be contacted", "type": "checkbox", "required": true }
  ]
}

string

required

Form title, up to 120 characters.

string

Up to 500 characters.

string

Shown after a submission. Absent means the default.

array

required

1-20 fields, each with key, label, type (text, textarea, number, email, checkbox), required and optional placeholder.

Submit a form

POST /public/workflow-forms/forms/submit with a JSON body.

string

required

The form token, 20-200 characters.

string

required

1-120 characters, unique per submission. Resending the same key returns the same response and never starts a second run, so retries after a network error are safe.

object

required

One entry per form field, keyed by the field’s key. Values are strings (up to 5,000 characters), numbers or booleans.

curl -X POST "https://<your Hive API host>/public/workflow-forms/forms/submit" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "'"$FORM_TOKEN"'",
    "idempotencyKey": "crm-lead-8841",
    "payload": {
      "full_name": "Ada Lovelace",
      "email": "ada@example.com",
      "details": "Quarterly close support",
      "consent": true
    }
  }'

import { randomUUID } from 'node:crypto';

const response = await fetch(
  'https://<your Hive API host>/public/workflow-forms/forms/submit',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      token: process.env.HIVE_FORM_TOKEN,
      idempotencyKey: randomUUID(), // store it and reuse it if you retry
      payload: { full_name: 'Ada Lovelace', email: 'ada@example.com', consent: true },
    }),
  },
);
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.code}: ${error.message}`);
}

200 OK

{ "status": "accepted" }

accepted means the submission was recorded. It says nothing about the run: whether it started, succeeded or was refused (for example because the workspace has used its run allowance) is never disclosed to the submitter. Follow runs in Past runs inside Hive.

Validation

The payload is checked against the live form:

every required field must be present; a required text field must not be blank, and a required checkbox must be true;
text up to 500 characters, textarea up to 5,000, email a valid address up to 200 characters, number a finite number;
keys the form does not declare are rejected.

Limits

Limit	Value
Requests per form token	20 per minute
Requests per client IP	60 per minute
Request body	64 KiB
Fields per form	20

Both rate limits apply to reads and submissions alike.

Errors

Errors use one envelope:

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded" } }

Status	Code	When
400	`invalid_input`	The body is not valid JSON, is missing a field, or the payload fails the form’s validation. The message names the problem.
404	`workflow_public_form_unavailable`	The token is unknown, rotated or no longer live. On a read, also when the token is missing or not 20-200 characters; on a submit, a missing or wrong-length token is a 400 `invalid_input`. Message: “This form is not available”.
413	`payload_too_large`	The body is over 64 KiB.
429	`rate_limited`	A rate limit was hit. Back off and retry with the same idempotency key.

What the run can do

Each accepted submission starts one production run of the live release, as the workflow’s owner and through the owner’s connected accounts. Its actions go through the workspace’s approval and safety policy. Treat submitted text as untrusted: it can steer an AI condition or agent.

Schedules and public forms

Publishing and managing form links.

Incoming webhooks

Send signed events into Hive.

Developer overview

Every way to build on Hive.

Limits reference

All limits in one table.

​Before you start

​Read a form

​Submit a form

​Validation

​Limits

​Errors

​What the run can do

​Related

Schedules and public forms

Incoming webhooks

Developer overview

Limits reference

Before you start

Read a form

Submit a form

Validation

Limits

Errors

What the run can do

Related