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, 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 $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": "Repo onboarding",
  "scope": { "type": "personal" },
  "blocks": [
    { "title": "Layout", "content": "apps/, server/, protobuf/" },
    { "title": "Local setup", "content": "npm install" }
  ]
}

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 $TOKEN"

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

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

In the API, agent usage, pack search, track search, and pack reads consume credits. GET /v1/packs is credit-gated for outline, selected-content, and full-content reads. See Credits API for balance and checkout behavior.

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, 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 can create, update, and delete multiple tracks in one request. Non-UUID draft IDs create new records and can be referenced by other drafts in the same request.

{
	"scope": { "type": "personal" },
	"updateDrafts": [
		{ "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.