REST API
Create, configure and delete forms, read submissions and manage spam, and manage webhook endpoints and deliveries with a secret key.
The REST API lets your server create, configure, pause and delete forms and their field schemas, read submissions, move them in and out of spam and delete them, and create, change, test and replay webhook endpoints. It is JSON over HTTPS at https://ikiform.com/api/v1. The OpenAPI 3.1 document is at /api/v1/openapi.json.
/api/v1. Post to the form endpoint with a secret key instead; see From a server.Working with an AI agent such as Claude Code or Cursor? Connect the MCP server instead: it offers the same actions as tools, with the same keys and scopes.
API keys
Create keys in the dashboard under API keys. A key belongs to one workspace and only sees that workspace. The full key is shown once; Ikiform stores only its hash.
| Kind | Prefix | Use |
|---|---|---|
| Secret | ik_sk_ | For servers. Calls the REST API with the scopes you choose, and can create submissions. |
| Publishable | ik_pub_ | For browsers. Can only submit forms, and only from the domains you list on the key. |
Scopes
| Scope | Grants |
|---|---|
forms:read | GET /forms, GET /forms/:formId |
forms:write | POST /forms, PATCH and DELETE /forms/:formId, PUT and DELETE /forms/:formId/fields |
submissions:read | GET /submissions, GET /submissions/:id |
submissions:write | DELETE /submissions/:id, POST /submissions/:id/spam and /not-spam, and posting to /f/:formId |
webhooks:read | GET /webhooks, GET /webhooks/:endpointId and /deliveries |
webhooks:write | POST /webhooks and PATCH /webhooks/:endpointId (with submissions:read), DELETE /webhooks/:endpointId, and POST to /roll-secret, /test and /replay |
A key keeps the scopes it was created with. Existing keys don't gain forms:write, webhooks:read or webhooks:write; create a new key with them.
Authentication
Send the secret key as a Bearer token. The API is server to server only: it sends no CORS headers and answers browser preflights with 405, so a secret key can never work from a web page.
curl https://ikiform.com/api/v1/forms \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"- A missing, malformed, unknown, revoked or expired key gets
401 unauthorizedwithWWW-Authenticate: Bearer. - A publishable key gets
403 forbidden(Publishable keys can only submit forms.). A key without the needed scope gets403 forbiddenwith the scope named in the message. - Responses are sent with
Cache-Control: no-store.
The SDK examples below share one client:
import { createClient } from "@ikiform/sdk";
const ikiform = createClient({ apiKey: process.env.IKIFORM_SECRET_KEY! });Request composer
curl "https://ikiform.com/api/v1/submissions?form_id=frm_xxxxxxxxxxxxxxxx&status=received&limit=50" \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"Run this from your server. The REST API refuses browser requests, so this page never sends it.
Endpoints
| Method | Path | Scope | Returns |
|---|---|---|---|
GET | /me | any | Check an API key |
GET | /forms | forms:read | List forms |
GET | /forms/:formId | forms:read | Get a form |
POST | /forms | forms:write | Create a form |
PATCH | /forms/:formId | forms:write | Update a form |
PUT | /forms/:formId/fields | forms:write | Publish a field schema |
DELETE | /forms/:formId/fields | forms:write | Remove the field schema |
DELETE | /forms/:formId | forms:write | Delete a form |
GET | /submissions | submissions:read | List submissions |
GET | /submissions/:id | submissions:read | Get a submission |
POST | /submissions/:id/spam | submissions:write | Mark as spam |
POST | /submissions/:id/not-spam | submissions:write | Mark as not spam |
DELETE | /submissions/:id | submissions:write | Delete a submission |
GET | /forms/:formId/fields | forms:read | List a form's fields |
GET | /forms/:formId/sample | submissions:read | Sample submission events |
GET | /webhooks | webhooks:read | List webhook endpoints |
POST | /webhooks | webhooks:write | Create a webhook endpoint |
GET | /webhooks/:endpointId | webhooks:read | Get a webhook endpoint |
PATCH | /webhooks/:endpointId | webhooks:write | Update a webhook endpoint |
POST | /webhooks/:endpointId/roll-secret | webhooks:write | Roll the signing secret |
DELETE | /webhooks/:endpointId | webhooks:write | Delete a webhook endpoint |
POST | /hooks | webhooks:write | Subscribe a REST hook |
DELETE | /hooks/:hookId | webhooks:write | Unsubscribe a REST hook |
GET | /webhooks/:endpointId/deliveries | webhooks:read | List deliveries |
POST | /webhooks/:endpointId/test | webhooks:write | Send a test event |
POST | /webhooks/:endpointId/replay | webhooks:write | Replay failed deliveries |
GET | /openapi.json | None | The OpenAPI document |
GET | /health | None | { "ok": true } |
Check an API key
GET /me with any scope.
- Works with any scope. Automation platforms call it to test a connection and to name it after the workspace.
curl https://ikiform.com/api/v1/me \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"List forms
GET /forms with the forms:read scope.
- Newest first. Takes
limit(1 to 100, default 25) andcursor.
curl "https://ikiform.com/api/v1/forms?limit=10" \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"Get a form
GET /forms/:formId with the forms:read scope.
- Also returns
fieldsanddefinition, the published field schema, ornullwhen the form has none and accepts any fields, and whethernotificationsare on.
curl https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"Create a form
POST /forms with the forms:write scope.
- Only
nameis required. Send JSON withContent-Type: application/json. - Post submissions to the returned
endpoint. Add a hidden input namedhoneypot_fieldand leave it empty. - It also takes every setting Update a form takes, except
status.
curl -X POST https://ikiform.com/api/v1/forms \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Waitlist", "allowed_domains": ["example.com"], "redirect_url": "https://example.com/thanks" }'Update a form
PATCH /forms/:formId with the forms:write scope.
- Send only what changes.
statusisactiveorpaused; a paused form refuses posts. A form Ikiform disabled returns403. - Send
[]ornullto clearallowed_domainsorredirect_url, andnullashoneypot_fieldfor_gotcha. spam_checkisoff,ikiform(our human check) orcustom(your Turnstile widget, withturnstile_site_keyandturnstile_secret). The secret is stored encrypted and never returned;nullremoves it and turnscustomoff.origin_mismatchisspamorrejectfor posts from sites outsideallowed_domains.rate_limittakespreset(standard,relaxed,strictorcustom), plusper_ip,window_seconds(10, 60, 600, 3600 or 86400) and optionalper_form_per_minuteforcustom. It is write-only, so bots can't read it.notifications: { "enabled": false }stops new-submission emails. Recipients are chosen in the dashboard.- Unknown fields return
400 invalid_requestnaming the field.
curl -X PATCH https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "status": "paused", "origin_mismatch": "reject", "rate_limit": { "preset": "strict" } }'Publish a field schema
PUT /forms/:formId/fields with the forms:write scope.
- The body is a form definition:
version1, atitleand up to 100fields, the same format as Fields. It can be up to 256 KB. - From then on, posts are validated against it and posts that don't match are rejected with
422. A definition with problems returns422 validation_failed, anderror.fieldslists them by path, likefields.0.type.
curl -X PUT https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx/fields \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "version": 1, "title": "Contact", "fields": [{ "id": "email", "type": "email", "label": "Email", "required": true }, { "id": "message", "type": "textarea", "label": "Message" }] }'Remove the field schema
DELETE /forms/:formId/fields with the forms:write scope.
- The form accepts any fields again.
curl -X DELETE https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx/fields \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"Delete a form
DELETE /forms/:formId with the forms:write scope.
- The endpoint stops accepting posts at once, and the form disappears from lists. Deleting again returns
404.
curl -X DELETE https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"List submissions
GET /submissions with the submissions:read scope.
| Parameter | Values | Default |
|---|---|---|
form_id | A form id | All forms in the workspace |
status | received or spam | Both |
limit | 1 to 100 | 25 |
cursor | next_cursor from the previous page | The first page |
- Newest first. A
form_idfrom another workspace returns an empty list rather than an error, so ids can't be probed.
curl "https://ikiform.com/api/v1/submissions?form_id=frm_xxxxxxxxxxxxxxxx&status=received&limit=50" \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"Get a submission
GET /submissions/:id with the submissions:read scope.
curl https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3 \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"Mark as spam
POST /submissions/:id/spam with the submissions:write scope.
- Moves a received submission to spam, lowers the form's
submission_count, cancels its pendingsubmission.createddeliveries and sendssubmission.updatedto subscribed endpoints. - Calling it on a submission that is already spam returns it unchanged.
curl -X POST https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3/spam \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"Mark as not spam
POST /submissions/:id/not-spam with the submissions:write scope.
- Moves it back to received, clears its spam score and reasons, and sends
submission.updatedto subscribed endpoints, plussubmission.createdto subscribed endpoints that never received one for it. - Calling it on a received submission returns it unchanged.
curl -X POST https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3/not-spam \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"Delete a submission
DELETE /submissions/:id with the submissions:write scope.
- Permanently removes the submission and its webhook deliveries, then sends
submission.deletedto subscribed endpoints. There is no undo. Deleting again returns404.
curl -X DELETE https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3 \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"List a form's fields
GET /forms/:formId/fields with the forms:read scope.
- Lists the fields a submission can carry, for mapping in Zapier, Make or n8n.
keyis the name the value has infields. sourceisdefinitionwhen the form has published fields. Otherwise the list is built from the keys of its 25 most recent submissions, with reserved_keys left out.
curl https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx/fields \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"Sample submission events
GET /forms/:formId/sample with the submissions:read scope.
- Returns up to 3 recent received submissions in exactly the body a
submission.createdwebhook carries, so a tool can show real data while you set it up. - A form without submissions gets one example built from its fields, with
submission_idset tosub_example.
curl https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx/sample \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"List webhook endpoints
GET /webhooks with the webhooks:read scope.
- Returns every endpoint in the workspace in one page.
- Signing secrets and custom header values are never returned.
header_nameslists the custom headers each delivery carries.
curl https://ikiform.com/api/v1/webhooks \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"Create a webhook endpoint
POST /webhooks with the webhooks:write scope.
urlfollows the endpoint URL rules. Omitform_idfor every form.event_typesdefaults tosubmission.created.headersis a list of{ name, value }, stored encrypted; see Custom headers.secretis returned only here, so store it now. Past your plan's endpoint limit you get402 plan_required.- Creating or changing an endpoint also needs
submissions:read, because the endpoint receives submission data.
curl -X POST https://ikiform.com/api/v1/webhooks \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/webhooks/ikiform", "form_id": "frm_xxxxxxxxxxxxxxxx", "headers": [{ "name": "Authorization", "value": "Bearer your-token" }] }'Get a webhook endpoint
GET /webhooks/:endpointId with the webhooks:read scope.
curl https://ikiform.com/api/v1/webhooks/whk_01k7v2b8f4h6j2k9m3n5p7q1r3 \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"Update a webhook endpoint
PATCH /webhooks/:endpointId with the webhooks:write scope.
- Send only what changes:
url,form_id,description,event_types,headersorstatus. status: "disabled"stops deliveries and"active"resumes them. Resuming doesn't send what was missed: replay it.headersreplaces the saved list;"value": nullkeeps a saved value. Whenurlchanges, send every value again so a token never reaches a new host by mistake.
curl -X PATCH https://ikiform.com/api/v1/webhooks/whk_01k7v2b8f4h6j2k9m3n5p7q1r3 \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "status": "disabled" }'Roll the signing secret
POST /webhooks/:endpointId/roll-secret with the webhooks:write scope.
- Returns a new signing secret once. The old one keeps working for 24 hours, so you can update your server without dropping deliveries.
curl -X POST https://ikiform.com/api/v1/webhooks/whk_01k7v2b8f4h6j2k9m3n5p7q1r3/roll-secret \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"Delete a webhook endpoint
DELETE /webhooks/:endpointId with the webhooks:write scope.
- Deletes the endpoint and its delivery history. Pending deliveries to it are dropped.
curl -X DELETE https://ikiform.com/api/v1/webhooks/whk_01k7v2b8f4h6j2k9m3n5p7q1r3 \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"Subscribe a REST hook
POST /hooks with the webhooks:write scope.
- Creates a webhook endpoint for an automation platform. It takes the same fields as Create a webhook endpoint, plus
managed_by:zapier,make,n8norautomation(the default). - It's a normal endpoint: it counts toward your plan's endpoint limit, shows in the dashboard and is signed. When its receiver answers
410 Gone, it's deleted without the usual email, because the platform has turned it off. - Needs
submissions:readtoo, because the hook receives submission data.
curl -X POST https://ikiform.com/api/v1/hooks \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://hooks.zapier.com/hooks/standard/123/abc", "form_id": "frm_xxxxxxxxxxxxxxxx", "managed_by": "zapier" }'Unsubscribe a REST hook
DELETE /hooks/:hookId with the webhooks:write scope.
- Deletes the hook and its delivery history, like Delete a webhook endpoint.
curl -X DELETE https://ikiform.com/api/v1/hooks/whk_01k7v2b8f4h6j2k9m3n5p7q1r3 \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"List deliveries
GET /webhooks/:endpointId/deliveries with the webhooks:read scope.
- Newest first.
statusissucceeded,pendingorfailed;failedincludes cancelled deliveries. Takeslimitandcursorlike the other lists. last_status_codeandlast_errorcome from the latest attempt.
curl "https://ikiform.com/api/v1/webhooks/whk_01k7v2b8f4h6j2k9m3n5p7q1r3/deliveries?status=failed&limit=50" \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"Send a test event
POST /webhooks/:endpointId/test with the webhooks:write scope.
- Queues an
endpoint.testevent and returns the delivery. List deliveries to see how your server answered. - A disabled endpoint returns
409 conflict. Enable it first.
curl -X POST https://ikiform.com/api/v1/webhooks/whk_01k7v2b8f4h6j2k9m3n5p7q1r3/test \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY"Replay failed deliveries
POST /webhooks/:endpointId/replay with the webhooks:write scope.
windowis24h,3dor7d. Every delivery created in that window that failed or was cancelled is sent again within about a minute, up to 1,000 per call.- If
moreistrue, call again to replay the rest. - A disabled endpoint returns
409 conflict. Test events are never replayed. See Replaying failed deliveries.
curl -X POST https://ikiform.com/api/v1/webhooks/whk_01k7v2b8f4h6j2k9m3n5p7q1r3/replay \
-H "Authorization: Bearer $IKIFORM_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "window": "24h" }'Objects
Objects are snake_case JSON with an object field. Timestamps are ISO 8601 in UTC with milliseconds. Submission, endpoint and delivery ids are ordered by time (sub_, whk_ and dlv_ plus 26 characters); form ids are random (frm_ plus 16 characters).
| Form field | Description |
|---|---|
status | active, paused or disabled |
submission_count | Received submissions, not spam |
endpoint | The URL to post submissions to |
honeypot_field | The hidden field bots fill in. Leave it empty in your form |
allowed_domains | Sites allowed to post, subdomains included. Empty allows any site |
redirect_url | Where browsers go after a plain HTML post, or null for the Ikiform thank-you page |
spam_check | off, ikiform or custom, with turnstile_site_key and turnstile_secret_set for custom |
origin_mismatch | spam or reject: what happens to posts from sites outside allowed_domains |
fields, definition, notifications | Only when retrieving, creating or updating one form. The field schema, or null without one, and whether new submissions are emailed |
| Webhook endpoint field | Description |
|---|---|
form_id | The one form it receives events for, or null for every form |
status | active or disabled, with disabled_reason when disabled |
event_types | The events it is subscribed to |
header_names | Custom headers sent with each delivery. Values are never returned |
failing_since, consecutive_failures, circuit_open_until | Failure tracking. Deliveries are paused until circuit_open_until after repeated failures |
| Delivery field | Description |
|---|---|
status | pending, succeeded, failed or cancelled |
attempt_count | Attempts so far |
last_status_code, last_error | Your server's status code, or the error, from the latest attempt |
next_attempt_at | When a pending delivery is tried next |
| Submission field | Description |
|---|---|
status | received or spam |
fields | The stored values |
meta | user_agent, origin, referrer, country, subject, reply_to. Every key is present and any value can be null. The IP hash is never returned |
spam.score, spam.reasons | The spam score and reasons, such as honeypot or origin_mismatch |
Pagination
Lists are newest first and use opaque cursors.
- Request without a cursor.
- If
has_moreis true, sendnext_cursorascursorwith the same filters. - Stop when
next_cursorisnull.
Pages are stable while new submissions arrive: new ones appear on the first page, never as duplicates further down. Don't build or parse cursors yourself; an invalid one returns 400 invalid_request.
for await (const submission of ikiform.submissions.iterate({ formId: "frm_xxxxxxxxxxxxxxxx" })) {
console.log(submission.id, submission.fields);
}Errors
Errors use the same envelope as form submissions. Every response has an X-Request-Id header, which errors repeat as request_id.
{
"ok": false,
"error": { "code": "forbidden", "message": "This API key is missing the forms:read scope." },
"request_id": "req_01k7v2c9t3e8m5q4x6z0a1b2c3"
}| Status | Code | When |
|---|---|---|
| 400 | invalid_request | A query parameter or body field is invalid; the message names it, and error.fields maps a body field to its messages |
| 400 | invalid_body | The body isn't a JSON object |
| 401 | unauthorized | Missing or invalid key |
| 402 | plan_required | Creating a webhook endpoint past the number your plan includes |
| 403 | forbidden | Publishable key, a missing scope, or resuming a form Ikiform disabled |
| 404 | not_found | Unknown route or id, or an id in another workspace, exactly like one that doesn't exist |
| 405 | method_not_allowed | A browser preflight |
| 409 | conflict | Testing or replaying a disabled webhook endpoint |
| 413 | payload_too_large | The body is over 16 KB, or 256 KB for a field schema |
| 415 | unsupported_media_type | The body isn't sent as application/json |
| 422 | validation_failed | A field schema has problems; error.fields lists them by path |
| 429 | rate_limited | Over the per-key rate limit |
| 500 | server_error | Something failed on our side; quote request_id |
Rate limit
Each key can make 100 requests per 60 seconds. Over the limit, the API returns 429 rate_limited with a Retry-After header in seconds. The SDK exposes it as error.retryAfter.
Dashboard only
API keys, members and invites, notification recipients and billing are managed in the dashboard only. A key that leaks can't create more keys, invite someone into your workspace, send email to new addresses or spend money.