FormPilot API Keys
Create scoped API keys for read-only FormPilot API access.
Status: Customer API keys and read-only API v1 are implemented in Pivot 04E.
FormPilot API keys let Pro and Business workspaces read their own forms and submissions from external systems. Tokens are workspace-scoped, scope-limited, and shown once when created or rotated.
Availability
API keys are available on Pro and Business plans, including active trials. Free and Starter workspaces cannot create or use API keys.
The dashboard permission required to manage keys is org:api_keys:manage.
Authentication
Send the token as a bearer token:
curl https://myformpilot.vercel.app/api/v1/forms \
-H "Authorization: Bearer fp_live_abc123xyz0_secret"Treat fp_live_... tokens like passwords. FormPilot shows the token once and
stores only a hash, so lost tokens must be rotated.
Scopes
Pivot 04E supports two read scopes:
| Scope | Access |
|---|---|
forms:read | Read forms and normalized field definitions. |
submissions:read | Read submissions, answers, summaries, and safe files |
submissions:write and API-based webhook management are not included in this
version.
Endpoints
GET /api/v1/forms
GET /api/v1/forms/{form_id}
GET /api/v1/forms/{form_id}/submissions
GET /api/v1/submissions/{submission_id}List endpoints return:
{
"data": [],
"next_cursor": null
}Use limit to request up to 100 rows:
GET /api/v1/forms?limit=100When next_cursor is not null, pass it back as cursor to read the next
page.
Form Shape
{
"id": "form_123",
"slug": "pressure-washing-quote",
"title": "Pressure washing quote",
"description": null,
"status": "published",
"fields": [
{
"id": "field_name",
"label": "Customer name",
"type": "short_text",
"description": "",
"required": true,
"options": [],
"rows": [],
"columns": []
}
],
"submission_count": 12,
"created_at": "2026-06-01T12:00:00.000Z",
"updated_at": "2026-06-01T12:00:00.000Z",
"published_at": "2026-06-01T12:00:00.000Z",
"archived_at": null
}Submission Shape
{
"id": "sub_123",
"form": {
"id": "form_123",
"slug": "pressure-washing-quote",
"title": "Pressure washing quote"
},
"submitted_at": "2026-06-01T12:00:00.000Z",
"updated_at": "2026-06-01T12:00:00.000Z",
"status": "new",
"answers": {
"field_name": "Test Customer"
},
"field_labels": {
"field_name": "Customer name"
},
"attachments": [
{
"upload_id": "upl_123",
"field_id": "field_photo",
"original_name": "driveway.jpg",
"content_type": "image/jpeg",
"size_bytes": 182400,
"kind": "image"
}
],
"summary": {
"status": "not_requested",
"text": null
}
}Attachment records include metadata only. Private upload URLs and upload file download URLs are not exposed through API v1.
Errors
Errors use one shape:
{
"error": {
"code": "missing_scope",
"message": "This API key does not have access to that resource."
}
}Common statuses:
| Status | Meaning |
|---|---|
400 | Invalid cursor or request parameter. |
401 | Missing, malformed, revoked, or invalid key. |
403 | Plan unavailable or missing scope. |
404 | Resource not found in the key workspace. |
429 | Rate limit exceeded. |
Rate limits are per key: Pro keys allow 120 requests per minute, and Business keys allow 600 requests per minute.
Safety Guarantees
API responses do not include IP addresses, user agents, cookies, authorization headers, private upload URLs, raw request headers, analytics data, or internal submission metadata.
API v1 is additive. Existing fields should not be renamed, removed, or change type without a new versioned contract.