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
- Open Account Settings → API Keys → Create API key.
- Name the key and select All workspaces or specific workspaces. All workspaces includes future memberships.
- 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.
- 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.
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.
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
GETCheck API health
Workspaces
GETList workspacesGETGet a workspacePATCHRename a workspace
Users
GETGet the current userGETGet a user
Members
Projects
GETList projectsPOSTCreate a projectPATCHRename a project
Forms
GETList formsPOSTCreate a formGETGet a formPATCHRename a formPOSTDuplicate a formPOSTMove a formPOSTTrash a formPOSTRestore a formPATCHSave a form draftPOSTPublish a formPOSTUnpublish a formPATCHSet form availabilityPATCHUpdate form settingsPATCHUpdate the form themePATCHReplace hidden fieldsPATCHReplace form variables
Submissions
GETList submissionsGETGet a submissionPATCHChange a submission categoryPATCHUpdate a submission answer
Errors
HeyForm returns JSON for endpoint errors. A stale draft version, for example, returns HTTP 409 with this body.
| Status | Meaning |
|---|---|
400 | A path parameter, query parameter, or JSON body is invalid. |
401 | The key is missing, invalid, expired, or no longer active. |
403 | The caller lacks a required scope, membership, or workspace access, or the operation is forbidden for that resource. |
404 | The resource is missing or unavailable to the caller. |
409 | The request conflicts with the resource's current version or state. |
429 | The instance's HTTP rate limit was reached. This response can be plain text. |