Public API — `/v1` リファレンス

正式仕様は OpenAPI 3.1 (apps/backend/openapi/public-api.yaml)。本ドキュメントは概念ガイド。

ベース

要素	値
Base URL	`https://api.tas-cha.com/v1`
Staging	`https://stg-api.tas-cha.com/v1`
Versioning	path (`/v1`) + 任意 `Tascha-Version: 2026-06-09`
Auth	API key または OAuth bearer。詳細: authentication.md
Request ID	`X-Request-Id` (任意送信、未指定なら server 発行)
Idempotency	`Idempotency-Key` (write 系のみ、任意 1-255 文字)

エンドポイント (read)

Method	Path	必要 scope	units
GET	`/v1/me`	`me:read`	1
GET	`/v1/organizations`	`organizations:read`	1
GET	`/v1/rooms`	`rooms:read`	1
GET	`/v1/rooms/:roomId/members`	`rooms:read`	1
GET	`/v1/rooms/:roomId/messages`	`messages:read`	1
GET	`/v1/rooms/:roomId/tasks`	`tasks:read`	1
GET	`/v1/rooms/:roomId/records`	`records:read`	1
GET	`/v1/rooms/:roomId/files`	`files:read`	1

DM ルーム (roomType=1) はすべて 404 (room_not_found) で返る。

エンドポイント (write)

Method	Path	必要 scope	units
POST	`/v1/rooms/:roomId/messages`	`messages:write`	3
POST	`/v1/rooms/:roomId/tasks`	`tasks:write`	3
PATCH	`/v1/rooms/:roomId/tasks/:taskId`	`tasks:write`	3
POST	`/v1/rooms/:roomId/records`	`records:write`	3
PATCH	`/v1/rooms/:roomId/records/:recordId`	`records:write`	3

write の共通規約:

user-actor token のみ。 acting user を持たない組織 API key 単独の write は 403 forbidden (メッセージ author / task・record creator が実在 user である必要があるため)
read より厳しい write 専用 burst limit (apiWriteBurstPerMinute: 30) が併用される
record の更新は creator のみ。 locked / archived は 403
リクエスト型は PublicCreate*Request / PublicUpdate*Request (packages/common)

Idempotency-Key

write 系に Idempotency-Key ヘッダー (任意) を付けると、同一リクエストの再送に同じ結果を返す (Stripe と同じ思想、 24h 保持):

同一 key + 異なるリクエスト内容 → 409 idempotency_conflict (reason: mismatch)
元リクエストが in-flight 中の再送 → 409 (reason: in_progress、二重実行しない)
失敗した key は再利用可能 (元の write が効果を持たないため)
結果 body は Redis cache + DB の両方に保持し、 cache が eviction / 再起動で消えても 24h 以内なら DB から replay する
24h を過ぎた再送 → 409 (reason: result_unavailable)。黙って再実行はしない
期限切れ row は日次 cron で物理削除される (テーブル無限成長の防止)

楽観ロック (task)

PATCH /v1/rooms/:roomId/tasks/:taskId は任意の version フィールドを受け取る。指定時、現在の task version と一致しなければ 409 version_conflict (details.currentVersion に現在値)。現在の version は write レスポンスで返る。

Pagination

cursor pagination (opaque base64url)。

リクエスト:

GET /v1/rooms?limit=20&cursor=eyJpZCI6Ii4uIn0

レスポンス:

{ "data": [...], "nextCursor": "eyJpZCI6Ii4uIn0" }

nextCursor === null で終端
cursor の中身は opaque (将来形式が変わっても互換)
limit は endpoint 毎に上限あり (cap=200)

エラー envelope

{
  "error": {
    "code": "room_not_found",
    "message": "Room was not found or is not accessible.",
    "requestId": "req_01JY...",
    "details": {}
  }
}

code 一覧

HTTP	code	例
400	`validation_error`	cursor 不正、 query 形式エラー
401	`unauthenticated`	token なし
401	`invalid_api_key`	hash 不一致
401	`expired_api_key`	有効期限切れ
401	`revoked_api_key`	revoke 済み
403	`insufficient_scope`	scope 不足
403	`forbidden`	ドメイン権限不足
404	`not_found` / `room_not_found`	未存在、アクセス権なし (BOLA 対策で混在)
409	`idempotency_conflict`	同 key で異なる payload (write only)
409	`version_conflict`	task の楽観ロック不一致 (write only)
429	`rate_limit_exceeded`	burst 超過
429	`api_units_exceeded`	月次 quota 枯渇
500	`internal_error`	server bug
503	`rate_limit_backend_unavailable`	Redis 等の依存停止

`not_found` vs `forbidden` の方針

BOLA 対策で、「存在しない」と「アクセス権がない」を区別しない。アクセス権のないリソースは 必ず 404 で返す (error.code: room_not_found 等)。

DTO 安定性

Public*Summary が stable shape。内部用の DTO とは独立しており、リクエスト/レスポンス契約は SemVer 的に維持する:

既存フィールド削除や型変更 → メジャー (/v2)
フィールド追加 → minor (/v1 内で OK)
enum 値追加 → 非破壊 (クライアントは未知 enum を扱える前提)

機密フィールド (password / refresh token / billing email / Stripe 顧客 ID) は /v1 には絶対に載せない。

バージョニング

path major version (/v1 → /v2) は不互換変更時のみ
Tascha-Version: 2026-06-09 日付 header は 将来予約。今は無視
deprecation policy: 1 つ前のバージョンを 6 ヶ月維持

共通制約

max body: 1 MB
max URL length: 8 KB
max header size: 32 KB

公開しないもの

カテゴリ	提供
Admin API	× 公開なし
Billing mutation	× 公開なし
MFA / passkey 管理	× 公開なし
Debug / batch / migration	× 公開なし
内部用 API	× 公開なし

ベース​

エンドポイント (read)​

エンドポイント (write)​

Idempotency-Key​

楽観ロック (task)​

Pagination​

エラー envelope​

code 一覧​

not_found vs forbidden の方針​

DTO 安定性​

バージョニング​

共通制約​

公開しないもの​

ベース