API reference

The Epismo HTTP API is available at https://api.epismo.ai. Application endpoints live under /v1. OAuth endpoints live under /oauth and well-known metadata paths. The API uses the same object model as the CLI and MCP server: packs, tracks, aliases, suggestions, workspaces, projects, scopes, and credits.

Authentication

Protected endpoints accept OAuth access tokens as bearer tokens.

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

Read endpoints require read scopes. Mutation endpoints require write scopes. Many /v1 endpoints accept workspaceId as a query parameter. If omitted, the request uses the token's default context or personal space.

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

Request conventions

• Use content-type: application/json for JSON request bodies.
• Update endpoints use PATCH semantics. Omitted fields stay unchanged.
• Dates use YYYY-MM-DD.
• Create and update calls use scope; search calls use scopes.
• workspaceId is passed as a query parameter on supported endpoints.

Core endpoint map

Create a 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 packs use blocks. Workflow packs use type: "workflow" and steps. Passing blocks to a workflow or steps to a context pack returns a validation error.

Read packs efficiently

Pack reads return outline data by default. For large packs, do not immediately request full=true unless the client truly needs everything. Read the outline first, then fetch selected blockIds or 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"

Pack references can be UUIDs, @alias, @handle/alias, share URLs, or hub URLs.

API credit costs are listed by operation in Credits API.

Create tracks

Task tracks represent concrete work.

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 tracks represent outcomes.

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

Task statuses are backlog, todo, in_progress, and done. Goal statuses are not_started, on_track, at_risk, postponed, and completed.

Search and filters

Pack search supports type, query, page, searchMode, scopes, and filter fields such as category, like, visibility, ownerId, minLikeCount, minSuccessCount, 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. It also accepts searchMode.

searchMode selects the ranking mode: keyword (default) or semantic (keyword matching plus vector similarity). Omit it for keyword search.

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

Bulk apply tracks

POST /v1/tracks/apply can create, update, and delete multiple tracks in one request. Non-UUID ids create new records and can be referenced by other upserts in the same request.

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

Errors

Errors are returned as JSON. Validation errors may include schema parsing details.

Retry only 429 and transient 5xx responses, and use backoff.