API リファレンス

Epismo と連携するための HTTP API ガイドです。

Epismo の HTTP API は https://api.epismo.ai で提供されます。アプリケーションのエンドポイントは /v1 配下にあり、OAuth のエンドポイントは /oauth と well-known のメタデータパスにあります。API は CLI や MCP と同じオブジェクトモデルを扱うため、パック、トラック、エイリアス、ワークスペース、プロジェクト、クレジットの考え方は共通です。

認証

保護されたエンドポイントは OAuth のアクセストークンを Bearer トークンとして受け取ります。

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

読み取り系エンドポイントには読み取りスコープ、変更系エンドポイントには書き込みスコープが必要です。多くの /v1 エンドポイントは workspaceId クエリパラメータを受け取ります。省略した場合、トークンのデフォルトコンテキストまたは個人スペースで実行されます。

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

リクエストの規約

JSON のリクエストボディを使うエンドポイントでは content-type: application/json を指定します。
更新系エンドポイントは PATCH 方式です。省略した項目は維持されます。
日付は YYYY-MM-DD です。
非公開データの作成・更新では scope、検索では scopes を使います。
workspaceId は対応するエンドポイントでクエリパラメータとして指定します。

主要なエンドポイント一覧

メソッド	パス	用途
POST	`/v1/otp-tokens`	サインイン用の OTP トークンを作成
GET/POST	`/v1/credits`	残高取得、またはチェックアウト開始
GET/POST/PATCH	`/v1/workspaces`, `/v1/workspaces/:workspaceId`	ワークスペースの一覧 / 作成 / 更新
GET/PUT/DELETE	`/v1/workspaces/:workspaceId/members`, `/v1/workspaces/:workspaceId/members/:userId`	ワークスペースメンバーの一覧 / 作成・更新 / 削除
GET/POST/PATCH/DELETE	`/v1/projects`, `/v1/projects/:projectId`	プロジェクトの管理
POST/PUT/DELETE	`/v1/projects/members/list`, `/v1/projects/:projectId/members`, `/v1/projects/:projectId/members/:userId`	プロジェクトメンバーの管理
GET/PUT/DELETE	`/v1/agents`	インストール済みエージェントの一覧 / 追加 / 削除
POST/PATCH/GET/DELETE	`/v1/tracks`, `/v1/tracks/:id`	トラックの管理
POST	`/v1/tracks/search`, `/v1/tracks/apply`	トラックの検索 / 一括適用
POST/PATCH/GET/DELETE	`/v1/packs`	`reference` クエリによるパックの管理
POST	`/v1/packs/search`, `/v1/packs/like`	パックの検索 / いいね
PUT/GET/DELETE	`/v1/aliases`, `/v1/aliases/:alias`	パックのエイリアスの管理
POST	`/v1/mcp/tokens`, `/v1/mcp/tokens/refresh`	MCP トークンの発行 / 更新
POST	`/v1/cli/tokens`	CLI トークンの発行

context pack の作成

POST /v1/packs
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "type": "context",
  "title": "Team onboarding",
  "scope": { "type": "personal" },
  "blocks": [
    { "title": "Where things live", "content": "Docs in Notion, code in GitHub, designs in Figma." },
    { "title": "How we work", "content": "Weekly planning on Mondays; ship behind feature flags." }
  ]
}

context pack は blocks を持ちます。workflow pack の場合は type: "workflow" と steps を使います。blocks と steps を逆に渡すとバリデーションエラーになります。

パックを効率的に読む

パックの読み取りはデフォルトでアウトラインのデータを返します。大きなパックをエージェントに渡す場合、最初から full=true にするより、アウトラインを見て必要な blockIds または stepIds だけを取得する方が安全です。

curl "https://api.epismo.ai/v1/packs?reference=@repo-onboarding" \
  -H "authorization: Bearer $EPISMO_TOKEN"

curl "https://api.epismo.ai/v1/packs?reference=@repo-onboarding&blockIds=b001,b002" \
  -H "authorization: Bearer $EPISMO_TOKEN"

パックの参照には UUID、@alias、@handle/alias、共有 URL、ハブ URL を使えます。

API のクレジット消費はクレジット API に操作別で記載しています。

トラックの作成

task track は具体的な作業です。

POST /v1/tracks
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "type": "task",
  "title": "Review docs",
  "scope": { "type": "personal" },
  "task": { "status": "todo", "dueDate": "2026-06-05" }
}

goal track は成果目標です。

{
	"type": "goal",
	"title": "Ship documentation v1",
	"scope": { "type": "projects", "ids": ["project-id"] },
	"goal": { "status": "on_track", "progress": 40 }
}

タスクのステータスは backlog, todo, in_progress, done です。ゴールのステータスは not_started, on_track, at_risk, postponed, completed です。

検索とフィルター

パックの検索は type, query, page, scopes と、category, like, visibility, ownerId, minLikeCount, minDownloadCount, updatedAtFrom, updatedAtTo などのフィルター項目を受け取ります。

トラックの検索は、assignee, goalId, parentId, dependsOn, doneAtFrom / doneAtTo などのタスク固有のフィルターに加えて、progressMin や progressMax などのゴール固有のフィルターを受け取ります。

{
	"type": "task",
	"query": "docs",
	"scopes": [{ "type": "personal" }],
	"filter": { "status": ["todo", "in_progress"] }
}

トラックの一括適用

POST /v1/tracks/apply は複数の作成 / 更新 / 削除を1リクエストで処理します。非 UUID の id は新規作成として扱われ、同じリクエスト内で依存関係として参照できます。

{
	"scope": { "type": "personal" },
	"upserts": [
		{ "id": "t001", "title": "Task A", "task": { "status": "todo" } },
		{ "id": "t002", "title": "Task B", "task": { "status": "todo", "dependsOn": ["t001"] } }
	]
}

エラー

エラーは JSON として返ります。バリデーションエラーではスキーマ解析の詳細が含まれることがあります。

ステータス	意味
400	不正な入力、ルートパラメータ、クエリパラメータ
401	Bearer トークンがない、または無効
402	クレジットが必要な操作に対してクレジットが不足
403	認証済みだが選択したスコープ / ワークスペースで許可されていない
404	レコードまたは参照が見つからない
409	不正な状態遷移や重複制約などの競合
429	レート制限。特に OTP の作成
500	予期しないサーバーエラー
502	上流サービスの失敗 / 不正なレスポンス

再試行は429と一時的な5xx に限定し、バックオフを入れてください。