REST API

REST API を使うと、サーバーからフォームと送信データを読み取り、送信データをスパムに移動または解除し、削除できます。https://ikiform.com/api/v1 で HTTPS 経由の JSON を使います。OpenAPI 3.1 のドキュメントは /api/v1/openapi.json にあります。

API キー

キーはダッシュボードの API keys で作成します。キーは 1 つのワークスペースに属し、そのワークスペースしか参照できません。キー全体が表示されるのは 1 回だけで、Ikiform はハッシュしか保存しません。

スコープ

認証

シークレットキーを Bearer トークンとして送ります。API はサーバー間専用です。CORS ヘッダーを送らず、ブラウザーのプリフライトには 405 で応答するため、シークレットキーが Web ページから使えることはありません。

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

• キーがない、不正な形式、存在しない、無効化された、期限切れの場合は、WWW-Authenticate: Bearer 付きの 401 unauthorized が返ります。
• 公開可能キーには 403 forbidden（Publishable keys can only submit forms.）が返ります。必要なスコープのないキーには、メッセージにスコープ名を含む 403 forbidden が返ります。
• レスポンスは Cache-Control: no-store 付きで送られます。

以下の SDK の例では、1 つのクライアントを共有します:

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

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

リクエストコンポーザー

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

エンドポイント

フォームの一覧

forms:read スコープで GET /forms。

• 新しい順。limit（1〜100、デフォルト 25）と cursor を受け取ります。

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

フォームを取得

forms:read スコープで GET /forms/:formId。

• 別のワークスペースのフォーム ID は、存在しない ID とまったく同じく 404 を返します。

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

送信データの一覧

submissions:read スコープで GET /submissions。

• 新しい順。別のワークスペースの form_id はエラーではなく空の一覧を返すので、ID を探られることはありません。

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

送信データを取得

submissions:read スコープで GET /submissions/:id。

• 別のワークスペースの ID は、存在しない ID とまったく同じく 404 を返します。

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

スパムとしてマーク

submissions:write スコープで POST /submissions/:id/spam。

• 受信済みの送信データをスパムに移動し、フォームの submission_count を減らし、保留中の Webhook の配信をキャンセルします。
• すでにスパムの送信データに対して呼び出すと、変更せずにそのまま返します。

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

スパムではないとマーク

submissions:write スコープで POST /submissions/:id/not-spam。

• 受信済みに戻し、スパムスコアと理由を消去し、一致するすべての Webhook エンドポイントに submission.created を送ります。
• 受信済みの送信データに対して呼び出すと、変更せずにそのまま返します。

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

送信データを削除

submissions:write スコープで DELETE /submissions/:id。

• 送信データとその Webhook の配信を完全に削除します。元に戻すことはできません。もう一度削除すると 404 が返ります。

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

オブジェクト

オブジェクトは object フィールドを持つ snake_case の JSON です。タイムスタンプはミリ秒付きの ISO 8601（UTC）です。送信 ID は時刻順（sub_ に続く 26 文字）、フォーム ID はランダム（frm_ に続く 16 文字）です。

ページネーション

一覧は新しい順で、不透明なカーソルを使います。

1. カーソルなしでリクエストします。
2. has_more が true なら、同じフィルターで next_cursor を cursor として送ります。
3. next_cursor が null になったら終了します。

新しい送信データが届いても、ページは安定しています。新しいものは最初のページに表示され、後ろのページで重複することはありません。カーソルを自分で組み立てたり解析したりしないでください。無効なカーソルは 400 invalid_request を返します。

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

エラー

エラーはフォームの送信と同じ形式を使います。すべてのレスポンスに X-Request-Id ヘッダーが付き、エラーではそれが request_id として繰り返されます。

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

レート制限

各キーは 60 秒あたり 100 リクエストまで送れます。上限を超えると、API は秒数を示す Retry-After ヘッダー付きで 429 rate_limited を返します。SDK ではこれを error.retryAfter として参照できます。