認証

Bearer トークン、スコープ、ワークスペースコンテキストを使った API リクエストの認証方法です。

すべての保護された API エンドポイントは OAuth のアクセストークンを要求し、Authorization ヘッダーに Bearer トークンとして送ります。このページでは、その送り方と、すべてのリクエストに共通する規約を説明します。

トークンを取得する

アクセストークンは Epismo の OAuth フローで取得します。全体の流れは OAuth を参照してください。CLI や MCP クライアントを統合する場合は、プロダクト専用のトークンエンドポイントを使うと、そのまま使えるアクセストークン(とリフレッシュトークン)が直接返ります。

アクセストークンは短命です。期限が切れたら、再サインインさせる代わりにリフレッシュトークンを新しいアクセストークンに交換します。トークンがない、または期限切れのリクエストは 401 を返します。

トークンを送る

curl https://api.epismo.ai/v1/packs/search \
  -H "authorization: Bearer $EPISMO_TOKEN" \
  -H "content-type: application/json" \
  -d '{"type":"context","query":"onboarding"}'

スコープ

トークンはスコープを持ち、何ができるかを決めます。

読み取り系エンドポイントには読み取りスコープが必要です。
変更系エンドポイント(作成 / 更新 / 削除)には書き込みスコープが必要です。

エンドポイントに必要なスコープをトークンが持たない場合、リクエストは 403 を返します。連携で実際に使うスコープだけを要求してください。

ワークスペースのコンテキスト

多くの /v1 エンドポイントは特定のワークスペースの中で動作できます。ワークスペースは workspaceId クエリパラメータで渡します。

curl "https://api.epismo.ai/v1/projects?workspaceId=$WORKSPACE_ID" \
  -H "authorization: Bearer $EPISMO_TOKEN"

workspaceId を省略すると、リクエストはトークンのデフォルトコンテキストで、トークンにデフォルトがなければ個人スペースで実行されます。挙動を予測可能にするため、特に自動化システムでは workspaceId を明示的に渡してください。

リクエストの規約

API 全体に共通し、例の一貫性を保ちます。

JSON ボディは content-type: application/json で送ります。
日付は YYYY-MM-DD です。
作成 / 更新の呼び出しは単一の scope、検索の呼び出しは scopes を取ります。
更新はページに明記がない限り PATCH 方式で、省略した項目は変更されません。

リクエストが失敗すると、レスポンスは error 項目を持ちます。ステータスコードの一覧とハンドリングはエラーを参照してください。