REST API

Mit der REST-API kann dein Server Formulare und Einsendungen lesen, Einsendungen in den Spam und wieder heraus verschieben und sie löschen. Sie spricht JSON über HTTPS unter https://ikiform.com/api/v1. Das OpenAPI-3.1-Dokument liegt unter /api/v1/openapi.json.

API-Schlüssel

Erstelle Schlüssel im Dashboard unter API keys. Ein Schlüssel gehört zu einem Workspace und sieht nur diesen Workspace. Der vollständige Schlüssel wird einmal angezeigt; Ikiform speichert nur seinen Hash.

Scopes

Authentifizierung

Sende den Secret Key als Bearer-Token. Die API funktioniert nur von Server zu Server: Sie sendet keine CORS-Header und beantwortet Browser-Preflights mit 405, daher kann ein Secret Key nie von einer Webseite aus funktionieren.

curl https://ikiform.com/api/v1/forms \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

• Ein fehlender, fehlerhafter, unbekannter, widerrufener oder abgelaufener Schlüssel erhält 401 unauthorized mit WWW-Authenticate: Bearer.
• Ein Publishable Key erhält 403 forbidden (Publishable keys can only submit forms.). Ein Schlüssel ohne den nötigen Scope erhält 403 forbidden, und die Meldung nennt den Scope.
• Antworten werden mit Cache-Control: no-store gesendet.

Die SDK-Beispiele unten nutzen alle denselben Client:

import { createClient } from "@ikiform/sdk";

const ikiform = createClient({ apiKey: process.env.IKIFORM_SECRET_KEY! });

Request-Builder

curl "https://ikiform.com/api/v1/submissions?form_id=frm_xxxxxxxxxxxxxxxx&status=received&limit=50" \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Endpunkte

Formulare auflisten

GET /forms mit dem Scope forms:read.

• Neueste zuerst. Akzeptiert limit (1 bis 100, Standard 25) und cursor.

curl "https://ikiform.com/api/v1/forms?limit=10" \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Ein Formular abrufen

GET /forms/:formId mit dem Scope forms:read.

• Eine Formular-ID aus einem anderen Workspace gibt 404 zurück, genau wie eine, die nicht existiert.

curl https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Einsendungen auflisten

GET /submissions mit dem Scope submissions:read.

• Neueste zuerst. Eine form_id aus einem anderen Workspace gibt statt eines Fehlers eine leere Liste zurück, sodass sich IDs nicht ausprobieren lassen.

curl "https://ikiform.com/api/v1/submissions?form_id=frm_xxxxxxxxxxxxxxxx&status=received&limit=50" \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Eine Einsendung abrufen

GET /submissions/:id mit dem Scope submissions:read.

• IDs aus einem anderen Workspace geben 404 zurück, genau wie IDs, die nicht existieren.

curl https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3 \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Als Spam markieren

POST /submissions/:id/spam mit dem Scope submissions:write.

• Verschiebt eine empfangene Einsendung in den Spam, senkt den submission_count des Formulars und bricht ihre ausstehenden Webhook-Zustellungen ab.
• Bei einer Einsendung, die schon Spam ist, wird sie unverändert zurückgegeben.

curl -X POST https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3/spam \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Als kein Spam markieren

POST /submissions/:id/not-spam mit dem Scope submissions:write.

• Verschiebt sie zurück zu „empfangen“, löscht ihren Spam-Score und die Gründe und sendet submission.created an jeden passenden Webhook-Endpunkt.
• Bei einer empfangenen Einsendung wird sie unverändert zurückgegeben.

curl -X POST https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3/not-spam \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Eine Einsendung löschen

DELETE /submissions/:id mit dem Scope submissions:write.

• Entfernt die Einsendung und ihre Webhook-Zustellungen dauerhaft. Das lässt sich nicht rückgängig machen. Erneutes Löschen gibt 404 zurück.

curl -X DELETE https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3 \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Objekte

Objekte sind JSON in snake_case mit einem Feld object. Zeitstempel sind ISO 8601 in UTC mit Millisekunden. Einsendungs-IDs sind zeitlich geordnet (sub_ plus 26 Zeichen); Formular-IDs sind zufällig (frm_ plus 16 Zeichen).

Paginierung

Listen sind nach Neuesten zuerst sortiert und nutzen opake Cursor.

1. Sende den Request ohne Cursor.
2. Wenn has_more true ist, sende next_cursor als cursor mit denselben Filtern.
3. Hör auf, wenn next_cursor null ist.

Seiten bleiben stabil, während neue Einsendungen eintreffen: Neue erscheinen auf der ersten Seite, nie als Duplikate weiter unten. Baue oder parse Cursor nicht selbst; ein ungültiger gibt 400 invalid_request zurück.

for await (const submission of ikiform.submissions.iterate({ formId: "frm_xxxxxxxxxxxxxxxx" })) {
  console.log(submission.id, submission.fields);
}

Fehler

Fehler nutzen dieselbe Hülle wie Formular-Einsendungen. Jede Antwort hat einen Header X-Request-Id, den Fehler als request_id wiederholen.

{
  "ok": false,
  "error": { "code": "forbidden", "message": "This API key is missing the forms:read scope." },
  "request_id": "req_01k7v2c9t3e8m5q4x6z0a1b2c3"
}

Rate-Limit

Jeder Schlüssel kann 100 Requests pro 60 Sekunden senden. Über dem Limit gibt die API 429 rate_limited mit einem Header Retry-After in Sekunden zurück. Das SDK stellt ihn als error.retryAfter bereit.