API reference

Epismo HTTP API は https://api.epismo.ai で提供されます。Application endpoint は /v1 配下にあり、OAuth endpoint は /oauth と well-known metadata path にあります。API は CLI や MCP と同じ object model を扱うため、pack、track、alias、workspace、project、credit の考え方は共通です。

Authentication

Protected endpoint は OAuth access token を bearer token として受け取ります。

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

Read endpoint には read scope、mutation endpoint には write scope が必要です。多くの /v1 endpoint は workspaceId query parameter を受け取ります。省略した場合、token の default context または personal space で実行されます。

curl "https://api.epismo.ai/v1/projects?workspaceId=<workspace-id>" \
  -H "authorization: Bearer $TOKEN"

Request conventions

• JSON request body を使う endpoint では content-type: application/json を指定します。
• 更新系 endpoint は PATCH semantics です。省略した field は維持されます。
• 日付は YYYY-MM-DD です。
• Private data の作成・更新では scope、検索では scopes を使います。
• workspaceId は supported endpoint で query parameter として指定します。

Core endpoint map

Create a context pack

POST /v1/packs
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "type": "context",
  "title": "Repo onboarding",
  "scope": { "type": "personal" },
  "blocks": [
    { "title": "Layout", "content": "apps/, server/, protobuf/" },
    { "title": "Local setup", "content": "npm install" }
  ]
}

Context pack は blocks を持ちます。Workflow pack の場合は type: "workflow" と steps を使います。blocks と steps を逆に渡すと validation error になります。

Read packs efficiently

Pack read は default で outline data を返します。大きな pack を agent に渡す場合、最初から full=true にするより、outline を見て必要な blockIds または stepIds だけを取得する方が安全です。

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

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

Pack reference には UUID、@alias、@handle/alias、share URL、hub URL を使えます。

API では agent usage、pack search、track search、pack read が credit を消費します。GET /v1/packs は outline、selected content、full content のいずれも credit-gated です。Credit の残高や checkout は Credits API を参照してください。

Create tracks

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 }
}

Task status は backlog, todo, in_progress, done です。Goal status は not_started, on_track, at_risk, postponed, completed です。

Search and filters

Pack search supports type, query, page, scopes, and filter fields such as category, like, visibility, ownerId, minLikeCount, minDownloadCount, updatedAtFrom, and updatedAtTo.

Track search supports task-specific filters such as assignee, goalId, parentId, dependsOn, and doneAtFrom / doneAtTo, plus goal-specific filters such as progressMin and progressMax.

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

Bulk apply tracks

POST /v1/tracks/apply は複数の create/update/delete を 1 request で処理します。非 UUID の draft ID は新規作成として扱われ、同じ request 内で依存関係として参照できます。

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

Errors

Error は JSON として返ります。Validation error では schema parsing の詳細が含まれることがあります。

Retry は 429 と一時的な 5xx に限定し、backoff を入れてください。