API 概要

Spantail は単一の REST API を中心に構築されています。Web アプリ、CLI、 MCP サーバーはいずれも同じエンドポイントのクライアントです。これらができることはすべて、HTTP で直接実行できます。

ベース URL

REST API はインスタンスの /api/v1 配下にあります。

https://<your-instance>/api/v1

<your-instance> は自分の Worker ドメイン（*.workers.dev の URL またはカスタムドメイン）に置き換えてください。一部のエンドポイントは /api/v1 の外にあります。認証は /api/auth （認証を参照）、ヘルスチェックは /api/health、公開共有ビューは /share 配下です。

安定性

Spantail は 1.0 より前のため、/api/v1 はリリース間で破壊的に変更される可能性があります。

v1.0.0 以降、/api/v1 は追加のみとなります。エンドポイントやフィールドの追加はありますが、削除も意味の変更も行いません。破壊的変更は既存の /api/v1 を残したまま /api/v2 として提供します。クライアントは、知らないレスポンスフィールドを無視するように書いてください。

すべての /api レスポンスは x-spantail-version ヘッダーにインスタンスのバージョンを載せます。追加のリクエストなしに、どのサーバと通信しているかを判別できます。

規約

原則 JSON。 リクエスト/レスポンスボディは application/json; charset=utf-8 です。ボディを伴うリクエストには必ず Content-Type: application/json を付けてください。一部のエンドポイントは代わりにバイナリを返します（例: アバターやワークスペースロゴの画像バイト）。詳細は各ページに記載します。
タイムスタンプ は UTC の ISO 8601 文字列です（例: 2026-06-28T09:30:00.000Z）。
日付は YYYY-MM-DD 形式のカレンダー日で、対象ユーザーのタイムゾーンで解釈されます（日付と時刻を参照）。
時間は整数の分です。
ID は不透明な文字列です。パースや組み立てをしないでください。
リクエストボディの 未知のフィールド は拒否されます。ボディは厳格に検証されます。

認証

ヘルス、共有ビュー、サインイン、招待の受諾といった一部の公開エンドポイントを除き、すべてのエンドポイントは認証が必要です。セッション cookie、Personal Access Token、Agent Access Token のいずれかで認証できます。モデル全体、トークン形式、スコープは認証を参照してください。

日付と時刻

タイムゾーンはユーザー単位の概念です（user.timezone、null は UTC）。ワークスペースやプロジェクトにはタイムゾーンはありません。日付とタイムスタンプは独立しています。

作業エントリの entryDate は作成者のタイムゾーンでのローカル日付文字列で、書き込み時に固定されます。
すべてのタイムスタンプは UTC の瞬間で、時間は整数の分です。
エージェントセッションはタイムスタンプのみを保持し、カレンダー日は読み取り時に閲覧者のタイムゾーンで startedAt から導出されます。
レポートは相対範囲と生成日を、実行ユーザーのタイムゾーンで解決します。

ページング

大きな結果セットを返しうる一覧エンドポイントは limit と offset クエリパラメータを受け付けます。 limit を省略したときの挙動はエンドポイント依存です。既定値と上限を持つもの（例: 作業エントリは既定 50・上限 200）もあれば、limit を任意とし全件を返すものもあります。挙動は各エンドポイントのページに記載しています。結果は素の JSON 配列で返るので、offset を増やしてページングします。

curl "https://<your-instance>/api/v1/work-entries?workspaceId=wrk_demo&limit=50&offset=50" \
  -H "Authorization: Bearer spantail_pat_yourtoken"

フィルタ

一覧エンドポイントはリソースごとのクエリパラメータを受け付けます。通常は workspaceId（必須）に加え、任意の projectId、userId、tag、from/to の日付範囲です。正確なパラメータは各リソースのページに記載しています。

エラー

エラーは適切な HTTP ステータスと構造化された JSON ボディで返されます。スタックトレースは決して公開されません。

{
  "error": {
    "code": "forbidden",
    "message": "Only the author can modify a work entry"
  }
}

コード	HTTP	意味
`bad_request`	400	不正なリクエスト（検証失敗、不正な状態遷移）。
`unauthorized`	401	資格情報が欠落・無効・期限切れ。
`forbidden`	403	認証済みだが操作が許可されていない。
`insufficient_scope`	403	Personal Access Token に必要なスコープがない。
`not_found`	404	リソースが存在しない、または呼び出し元から隠されている。
`conflict`	409	現在の状態と競合（例: slug の重複）。
`rate_limited`	429	この資格情報のリクエストが多すぎる。バックオフして再試行。
`internal`	500	予期しないサーバーエラー。

レート制限

書き込みや取り込みが多いエンドポイント（作業エントリの作成、エージェント活動の取り込み）は、資格情報単位（トークン、またはセッションの場合はユーザー単位）でレート制限されます。上限を超えるとコード rate_limited の 429 を返します。バックオフして再試行してください。

ヘルスチェック

GET /api/health public は認証なしで { "status": "ok" } を返します。稼働監視に使えます。