Skip to main content
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 a system you run. Workflows have no webhook URL of their own, and Hive has no customer API keys. Apps connected in Integrations can start a workflow through a Connected app event trigger. To send events into Signals instead, use an incoming webhook.

Before you start

  1. Build a workflow with a Public form trigger and deploy it.
  2. Select Form link, then Create form link, and copy the link. Select Form link again later to copy the same link. It looks like https://<your Hive app>/forms?token=<token>.
  3. 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 keeps working when the workflow’s owner deploys it again, as long as the live release still has the same form step; submissions are then checked against, and run, the live release. It stops working when the link is reset (Reset link), the live release no longer has that form step, someone who can’t manage sharing on the workflow (or anyone, through an AI client over MCP) deploys a new release or re-activates one other than the live one or the one the link was created on, the workflow is paused, returned to draft or deleted, or its owner can no longer run it. A link created before 5 October 2026 also stops working at the next deploy; reset it once for one that lasts. 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.
200 OK
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 key of an accepted submission within ten minutes returns accepted again and never starts a second run, so retries after a network error are safe. A key whose submission was refused or failed is not kept, so the same submission can be sent again with it. Hive also treats the same answers sent to the same form within a ten-minute window as one submission, whatever key they carry, so changing the key never starts extra runs.
object
required
One entry per form field, keyed by the field’s key. Values are strings (up to 5,000 characters), numbers or booleans.
string
Optional. Leave it out or send it empty. It is a spam trap that Hive’s hosted form keeps hidden, so only automated form-fillers write it: any non-empty value is refused with 400 invalid_input and starts no run.
200 OK
accepted means the submission was recorded. It says nothing about how the run went: whether it succeeded is never disclosed to the submitter. A submission refused at a limit (the form’s daily or monthly run limit, a pause for unusual traffic, a trial’s public runs, the workflow’s credit limit, or a workspace out of credits) is not accepted: it is answered 429 workflow_public_form_limit_reached (see Errors), so the submitter knows it was not sent. Follow runs in Past runs inside Hive. A refused submission is recorded as a Failed run that names the reason. If the next refusal has the same reason and no other run of that workflow came in between, Hive does not record it again. If the workflow’s owner has left the workspace or no longer has the Operator role or above, the submission is still accepted, but Hive starts no run and records nothing.

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

The per-IP limit covers reads and submissions together; each form token has its own read limit and its own submission limit. A submission past a form’s daily or monthly run limit, sent while the form is paused for unusual traffic (an hour at 10 times its usual level, and at least 100 runs, pauses it until the hour ends), past a trial’s public runs, or refused by the workflow’s or workspace’s credit limits or plan, is answered 429 workflow_public_form_limit_reached and starts no run: it was not sent. Days are counted in UTC.

Errors

Errors use one envelope:

What the run can do

Each submission Hive admits (one not refused for one of the reasons above) starts one production run of the live release, as the workflow’s owner and through the owner’s connected accounts. Its action steps are carried out whatever the owner’s accounts are set to or capped at, except a step whose recipient, channel, number or link came from the submission, an AI step’s answer or a web search: that step waits for the owner’s approval as a card, and the run carries on without it. The one exception is an acknowledgement: an email to the address the visitor submitted is sent with no card when everything else in it is text typed into the step or values from that same submission. If it also includes an AI step’s answer, an app’s data, web search text or an app event’s value, it waits too (see Where a workflow step sends). Only an Approval step you add to the workflow pauses the run for a person. The workspace’s limits — the kill switch, the recipient checks, the hourly action limit and the spend caps — can still stop an action: the action is not sent, its step fails with the reason, is not retried, and the run fails, even when the step is set to continue on error (see Why an action was not sent). Treat submitted text as untrusted: it reaches AI steps marked as data, never as instructions (see Run data reaches the AI as data), but an AI step still reads it and can be swayed by it, and an acknowledgement email that reads an address from the form goes to any valid address the visitor enters.

Credits and models

Each submission Hive admits is a workflow run. On Business, it counts as one of the workflow owner’s workflow runs, and its AI steps use the owner’s AI credits. On an earlier plan, its AI steps use credits from your workspace’s pool, inside the public budget: at most 25% of the month’s included credits (your trial credits during a trial), for public forms and public agent links together. Rolled-over credits, top-ups and bonus credits don’t raise it. Public traffic never triggers auto top-up, and uses credit top-ups only if an Owner or Admin allows it under Settings → Usage → Spend controls. A simple run typically uses about 3 credits; a run with agent steps uses more, depending on the work its steps do. AI steps in a run started by a public form run on an Efficient model by default. The form’s publisher can turn on Balanced for stronger answers, at about 9 times the credits (about 27 credits a simple run). Frontier models never run for public forms. The workflow’s own credit limits apply as well.

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.