Skip to content

Lists, retries and edits

Lists are newest first and paged by cursor:

Request
GET /v1/forms/frm_7f3kq2m4xa/submissions?limit=50&cursor=sub_01JC8H2K4M7P9X3V5B8N1Q6W2T
Response
{ "data": [ … ], "nextCursor": "sub_01JC7Z4N8K2W6R9T3B5X1M7Q4D" }
  • limit is 25 by default, and 100 at most.
  • nextCursor is null on the last page. Pass it back as cursor.
  • 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.
every-submission.ts
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);
}

Send Idempotency-Key on any POST, and a retry after a lost response does the work once:

Terminal window
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, with Retry-After: 1.

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.

Terminal window
# 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-Match is 428 precondition_required.
  • A stale one is 412 precondition_failed, and its body carries the current version, so you can merge and try again:
412 response
{
"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" }
}

Too many requests answers 429, always with Retry-After in seconds. Wait that long and try again. See Limits.

Was this helpful?

Your answer goes straight to the person who wrote it.

Thanks. We read every note and update the article.

Thanks, that helps us keep these useful.

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