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
- Build a workflow with a Public form trigger and deploy it.
- 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>. - 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.
/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.
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
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.
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.One entry per form field, keyed by the field’s
key. Values are strings (up to 5,000
characters), numbers or booleans.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; textup to 500 characters,textareaup to 5,000,emaila valid address up to 200 characters,numbera 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.Related
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.