REST API

Authenticate with an account API key and use the HeyForm REST API on your self-hosted instance.


The HeyForm REST API lives at /api/v1 on your self-hosted instance. It uses JSON and bearer authentication.

Create an API key

  1. Open Account Settings → API Keys → Create API key.
  2. Name the key and select All workspaces or specific workspaces. All workspaces includes future memberships.
  3. Select permissions available in every selected workspace. Choose 1 month (the default), 1 year, Custom date, or Never expires. A custom date includes that entire day in UTC.
  4. Copy the key to your integration's secret store. The full ak-heyform- key appears when you create or rotate it. HeyForm stores a SHA-256 hash and short display fragments.

In API Keys, you can change a key's scopes and workspaces, rotate it, or delete it. Editing keeps the secret. Rotating keeps the scopes, workspaces, and expiry and immediately invalidates the old secret. Create a new key when one expires. Deleting a key immediately revokes it. Account Settings manages keys using your browser session.

Workspace owners can grant workspaces:write and members:write. Workspace membership grants workspaces:read, users:read, members:read, projects:read, and projects:write. Form and submission permissions require project membership. HeyForm rechecks your current membership and role on each request, and limits existing-project operations to projects you can access.

Send requests

Set these variables before running the cURL examples.

Environment
export HEYFORM_URL="https://forms.example.com"
export HEYFORM_API_KEY="your-account-key"
curl --fail-with-body \
  -H "Authorization: Bearer ${HEYFORM_API_KEY}" \
  "${HEYFORM_URL}/api/v1/workspaces"

Use the workspace id from the response to list its projects, then use a project id to list its forms. Substitute the relevant IDs for the path placeholders below. Pass query parameters in the URL.

Send body parameters as JSON with Content-Type: application/json.

curl --fail-with-body -X POST \
  -H "Authorization: Bearer ${HEYFORM_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Customer feedback"}' \
  "${HEYFORM_URL}/api/v1/projects/${PROJECT_ID}/forms"

Use IDs returned by your instance to replace sample IDs in JSON bodies and to set path variables such as WORKSPACE_ID, PROJECT_ID, and FORM_ID. Submit JSON with the Content-Type: application/json header.

Endpoint reference

Health

Workspaces

Users

Members

Projects

Forms

Submissions

Errors

HeyForm returns JSON for endpoint errors. A stale draft version, for example, returns HTTP 409 with this body.

{
  "statusCode": 409,
  "message": "Invalid draft version or form status",
  "error": "Conflict"
}
StatusMeaning
400A path parameter, query parameter, or JSON body is invalid.
401The key is missing, invalid, expired, or no longer active.
403The caller lacks a required scope, membership, or workspace access, or the operation is forbidden for that resource.
404The resource is missing or unavailable to the caller.
409The request conflicts with the resource's current version or state.
429The instance's HTTP rate limit was reached. This response can be plain text.