Lists, retries and edits
Lists are newest first and paged by cursor:
GET /v1/forms/frm_7f3kq2m4xa/submissions?limit=50&cursor=sub_01JC8H2K4M7P9X3V5B8N1Q6W2T{ "data": [ … ], "nextCursor": "sub_01JC7Z4N8K2W6R9T3B5X1M7Q4D" }limitis 25 by default, and 100 at most.nextCursorisnullon the last page. Pass it back ascursor.- Cursors hold steady while new items arrive, so paging never skips or repeats.
- Lists don’t include a total. Counts that matter, such as a site’s submissions, have their own route.
async function* submissions(formId: string) { let cursor: string | null = null; do { const url = new URL(`https://api.seaforms.io/v1/forms/${formId}/submissions`); url.searchParams.set("limit", "100"); if (cursor) url.searchParams.set("cursor", cursor); const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.SEAFORMS_API_KEY}` } }); if (!res.ok) throw new Error(`Seaforms answered ${res.status}`); const page = (await res.json()) as { data: unknown[]; nextCursor: string | null }; yield* page.data; cursor = page.nextCursor; } while (cursor);}Retrying a POST
Section titled “Retrying a POST”Send Idempotency-Key on any POST, and a retry after a lost response does the work once:
curl -X POST https://api.seaforms.io/v1/forms \ -H "Authorization: Bearer $SEAFORMS_API_KEY" \ -H "Idempotency-Key: 5b0e2c1a-7f34-4d3e-9a61-2f8c6b1d4e90" \ -H "Content-Type: application/json" \ -d '{ "siteId": "site_01JC8H2K4M9V6Q3T7X0B5N2R8D", "name": "contact" }'- Up to 255 characters. A UUID is ideal.
- A successful answer is kept for 24 hours. The same key and body gets the same answer again, with
Idempotent-Replayed: true. - The same key with a different body is
422 idempotency_key_reused. - A repeat while the first is still running is
409 conflict, withRetry-After: 1.
Editing safely
Section titled “Editing safely”Two people can have the same form open. So the draft and the live config use ETags: read one, then send its ETag back as If-Match when you change it.
# Read it, and note the ETag header.curl -i https://api.seaforms.io/v1/forms/frm_7f3kq2m4xa/live \ -H "Authorization: Bearer $SEAFORMS_API_KEY"
# Change it, saying which version you read.curl -X PATCH https://api.seaforms.io/v1/forms/frm_7f3kq2m4xa/live \ -H "Authorization: Bearer $SEAFORMS_API_KEY" \ -H 'If-Match: "l-7a91"' \ -H "Content-Type: application/merge-patch+json" \ -d '{ "status": { "state": "paused", "message": "Back on Monday." } }'- A missing
If-Matchis428 precondition_required. - A stale one is
412 precondition_failed, and its body carries the current version, so you can merge and try again:
{ "type": "https://developer.seaforms.io/api/errors/#precondition_failed", "status": 412, "code": "precondition_failed", "title": "Someone else saved first", "current": { "etag": "\"l-91c2\"", "document": { "…": "…" }, "updatedAt": "2026-11-12T09:41:07Z", "updatedBy": "Mia" }}Rate limits
Section titled “Rate limits”Too many requests answers 429, always with Retry-After in seconds. Wait that long and try again. See Limits.
ChatGPT is a trademark of OpenAI, and Claude and Claude Code are trademarks of Anthropic. Other product names and logos belong to their owners. None of them makes or endorses Seaforms. Trademarks