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 |
| GET | /v1/event-types | events:read | 1 |
DM ルーム (roomType=1) はすべて 404 (room_not_found) で返る。
GET /v1/event-types は webhook が購読できる event 種別のカタログを返す。 room に依存しない。 stable=false の event は preview 扱いで、 安定化までは破壊的変更が入り得る。
エンドポイント (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)
エンドポイント (webhook 配信履歴)
| Method | Path | 必要 scope | units |
|---|---|---|---|
| GET | /v1/rooms/:roomId/webhooks/:webhookId/deliveries | webhooks:read | 1 |
| POST | /v1/rooms/:roomId/webhooks/:webhookId/deliveries/:deliveryId/redeliver | webhooks:write | 1 |
- 配信履歴の一覧は
limit(既定 50 / 最大 200) とcursorでページングする。 新しい順 (id desc)。 payloadと受信側 response の preview は 返さない (二次漏洩リスクの低減)。- redeliver は write だが unit cost は 1 (
WEBHOOK_DELIVERY)。 挙動の詳細は webhooks.md を参照。 - webhook の登録・更新・削除・secret rotation は Public API では扱わない (設定画面
/settings/developerから行う)。
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 | × 公開なし |