Skip to content

20_API仕様

本章では、filix-shadowwork-api が提供する Application Programming Interface（API）の外部仕様を定義する。
各エンドポイントの目的、入力、出力、認証、およびエラー形式を示し、フロントエンドとの契約（contract）とする。

共通仕様

ベースURL

  • 環境ごとに異なる（例: Cloudflare Workers のデプロイ先）
  • 以降のパスはすべてベースURL配下の相対パスとして記載する

Content-Type

  • リクエストボディがある場合は原則 application/json
  • レスポンスは原則 application/json

認証（Authentication）

本APIは、ユーザー識別子（user_id）をもとに処理対象を特定する。
認証方式（トークン等）や user_id の受け渡し方法は、セキュリティ要件とあわせて 50_セキュリティ に記載する。

注: 本章では「どの方式で認証するか」ではなく、API契約として「どの情報が必要か」「どう返すか」を記載する。

利用権限（Authorization / 利用権限）

有料状態（paid）などの利用権限は、各機能のアクセス可否に影響する。
paid判定や webhook 反映の詳細は 40_課金と利用権限 に記載する。

クエリパラメータ

  • GET の取得系ではクエリパラメータを使用する場合がある（詳細は各エンドポイント）

共通エラー形式（Error response）

すべてのエンドポイントは、失敗時に共通の JSON 形式でエラーを返す。

{
  "ok": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "説明文（人間向け）"
  }
}
  • ok: 成否フラグ（失敗時は false）
  • error.code: エラー種別（例: BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, INTERNAL_ERROR）
  • error.message: 画面表示やログのための説明文

HTTPステータスはエラー種別に応じて設定する（例: 400/401/403/404/500）。
※実装上のステータス割当は変更され得るが、成功時に ok: true を返すこと、失敗時に上記形式を返すことを契約とする。

エンドポイント一覧

ヘルスチェック

  • GET /
    サービス稼働確認。

課金・利用権限

  • GET /api/paid
    指定ユーザーの paid 状態を返す。
  • POST /api/admin/set_paid
    管理用途。指定ユーザーの paid 状態を更新する。

スレッド（thread）

  • POST /api/thread/start
    スレッド開始。
  • POST /api/thread/message
    スレッドにメッセージを追加し、必要に応じて応答を返す。
  • GET /api/thread/state
    スレッド状態取得。
  • POST /api/thread/close
    スレッド終了。
  • GET /api/thread/messages
    スレッドのメッセージ一覧取得。

実行（run）

  • POST /api/run/start
    実行開始。
  • POST /api/run/restart
    実行再開（続きから進める想定）。
  • GET /api/runs/list
    実行一覧取得。

スレッド一覧

  • GET /api/threads/list
    スレッド一覧取得。

LLM（管理・検証用途）

  • POST /api/llm/ping
    LLM疎通確認。
  • POST /api/llm/respond
    LLM応答生成（検証・開発用途を想定）。

エンドポイント仕様（詳細）

以下は「最低限の契約」を示す。
リクエスト/レスポンスの厳密なフィールド定義（JSON schema）は必要になった段階で追加する。

GET /

目的: 稼働確認。
認証: 不要。
成功レスポンス例: 

{ "ok": true }

GET /api/paid

目的: 指定ユーザーの paid 状態を返す。
認証: 必要（方式は 50_セキュリティ）。
入力: クエリ - user_id（必須）

成功レスポンス例: 

{ "ok": true, "paid": true }

POST /api/admin/set_paid

目的: 管理用途で paid 状態を更新する。
認証: 管理者向けの制限が必要（詳細は 60_利用制限と運用ポリシー または 50_セキュリティ）。
入力: JSON（例） 

{ "user_id": "xxx", "paid": true }

成功レスポンス例: 

{ "ok": true }

POST /api/thread/start

目的: シャドウワークのスレッドを開始する。
認証: 必要。
入力: JSON（例） 

{ "user_id": "xxx" }

成功レスポンス（例）: 

{ "ok": true, "thread_id": "t_xxx", "run_id": "r_xxx" }

POST /api/thread/message

目的: スレッドにメッセージを追加し、必要に応じて応答を返す。
認証: 必要。
入力: JSON（例） 

{ "user_id": "xxx", "thread_id": "t_xxx", "message": "text" }

成功レスポンス（例）: 

{ "ok": true, "reply": "text", "thread_state": { } }

GET /api/thread/state

目的: スレッドの状態を取得する。
認証: 必要。
入力: クエリ（例） - user_id（必須） - thread_id（必須）

成功レスポンス（例）: 

{ "ok": true, "state": { } }

POST /api/thread/close

目的: スレッドを終了する。
認証: 必要。
入力: JSON（例） 

{ "user_id": "xxx", "thread_id": "t_xxx" }

成功レスポンス（例）: 

{ "ok": true }

GET /api/thread/messages

目的: スレッドに紐づくメッセージ一覧を取得する。
認証: 必要。
入力: クエリ（例） - user_id（必須） - thread_id（必須）

成功レスポンス（例）: 

{ "ok": true, "messages": [ { } ] }

POST /api/run/start

目的: 実行（run）を開始する。
認証: 必要。
入力: JSON（例） 

{ "user_id": "xxx" }

成功レスポンス（例）: 

{ "ok": true, "run_id": "r_xxx" }

POST /api/run/restart

目的: 実行（run）を再開する。
認証: 必要。
入力: JSON（例） 

{ "user_id": "xxx", "run_id": "r_xxx" }

成功レスポンス（例）: 

{ "ok": true, "run_id": "r_xxx" }

GET /api/runs/list

目的: 指定ユーザーの実行（run）一覧を返す。
認証: 必要。
入力: クエリ（例） - user_id（必須）

成功レスポンス（例）: 

{ "ok": true, "runs": [ { } ] }

GET /api/threads/list

目的: 指定ユーザーのスレッド一覧を返す。
認証: 必要。
入力: クエリ（例） - user_id（必須）

成功レスポンス（例）: 

{ "ok": true, "threads": [ { } ] }

POST /api/llm/ping

目的: LLM疎通確認。
認証: 原則必要（開発用途のため制限推奨）。
入力: JSON（必要なら） 

{ "ok": true }

POST /api/llm/respond

目的: LLM応答生成（検証用途）。
認証: 原則必要（開発用途のため制限推奨）。
入力: JSON（例） 

{ "prompt": "text" }

成功レスポンス（例）: 

{ "ok": true, "reply": "text" }

備考（実装との整合性）

  • 各リクエスト/レスポンスの詳細フィールドは、実装の進展に合わせて追記する。
  • 本章は「詳細設計」ではなく、フロントとバックの契約として必要な事項に限定して記載する。