メインコンテンツまでスキップ

Quickstart — 最初の /v1 リクエスト

1. API key を発行する​

  1. TAS-CHA にログイン → 設定 → Developer タブ (/settings/developer)
  2. 「新規発行」をクリック
  3. name (用途が分かる名前)、 必要な scope、 mode (live or test) を選ぶ
  4. 発行直後に表示される tcha_live_... token を その場でコピーして保管
    • 一度ダイアログを閉じると 二度と表示できない
    • 紛失したら新しい key を作り、 古い key を revoke する

scope は最小権限で。 例: read-only な BI 連携なら rooms:read messages:read records:read の 3 つだけで十分。

scope は key 単位で固定: token は発行時に選んだ scope の範囲しか呼べない。 含まれない endpoint は 403 insufficient_scope になり、 details.granted に付与済み scope が返る。 下の GET /v1/me を試すには me:read scope が必要 (付けずに発行した key では最初のリクエストで 403 になる)。

2. 最初のリクエスト​

TOKEN="tcha_live_xxxxxxxx..."

curl -sS https://api.tas-cha.com/v1/me \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Request-Id: req_$(uuidgen)"

レスポンス例:

{
  "id": "ckabc1234",
  "email": "you@example.com",
  "name": "あなたの名前",
  "locale": "ja",
  "organizationId": null,
  "billingContext": "individual",
  "createdAt": "2026-06-09T00:00:00.000Z"
}

3. レスポンス header を読む​

X-Request-Id: req_01JY...
RateLimit-Limit: 300
RateLimit-Remaining: 299
RateLimit-Reset: 42
RateLimit-Policy: 300;w=60
Tascha-Api-Units-Limit: 20000
Tascha-Api-Units-Remaining: 19999
Tascha-Api-Units-Used: 1
Tascha-Api-Units-Cost: 1
Tascha-Api-Units-Reset: 2026-07-01T00:00:00+09:00
Tascha-RateLimit-Scope: user
  • RateLimit-*: 直近 60 秒間の burst 状況 (IETF 形式)
  • Tascha-Api-Units-*: 月次の API units 状況 (TAS-CHA 固有)
  • 詳細: rate-limits.md

4. リソース一覧を取る​

curl -sS "https://api.tas-cha.com/v1/rooms?limit=20" \
  -H "Authorization: Bearer $TOKEN"
{
  "data": [
    {
      "id": "ck...",
      "name": "プロジェクトA",
      "roomType": 0,
      "organizationId": null,
      "createdById": "ck...",
      "createdAt": "2026-05-01T00:00:00.000Z",
      "updatedAt": "2026-05-01T00:00:00.000Z"
    }
  ],
  "nextCursor": "eyJpZCI6ImNrYWJjMTIzNCJ9"
}

nextCursor が null でなければ次のページがある。 そのまま ?cursor=... に渡す。

5. 失敗時の挙動​

すべて以下のエラー envelope:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Token does not have required scopes",
    "requestId": "req_01JY...",
    "details": { "required": ["rooms:read"], "granted": [] }
  }
}

詳細: public-api.md

やってはいけないこと​

  • token を console.log / Git / Slack / メールに貼らない
  • 1 つの token に全 scope を付与しない (用途別に発行する)
  • ブラウザ向け SPA で API key を直接使わない (前段サーバーを置く)
  • public Gist や JSFiddle 等に貼って動作確認しない

詳細: security.md