REST API

Base URL: /api

All endpoints accept and return JSON unless otherwise noted.

---

Sessions

Method	Path	Description
GET	/sessions	List sessions for a workspace. Requires ?workspaceId query param.
GET	/sessions/:id	Get a single session by ID. Requires ?workspaceId query param.
DELETE	/sessions/:id	Delete a session. Requires ?workspaceId query param.

---

Workspaces

Method	Path	Description
GET	/workspaces	List all workspaces.
GET	/workspaces/:id	Get a workspace by ID.
POST	/workspaces	Create a workspace. Body: { name, rootPath? }
PUT	/workspaces/:id	Update a workspace.
DELETE	/workspaces/:id	Delete a workspace.
PUT	/workspaces/reorder	Reorder workspaces. Body: { ids: string[] }
POST	/workspaces/:id/open	Open/activate a workspace.
GET	/workspaces/:id/tree	Get recursive directory tree. Optional ?depth (1-5, default 3).
GET	/workspaces/:id/list-files	List recent files in the workspace root (max 10, sorted by mtime).
GET	/workspaces/:id/memory	Read the workspace memory file (.cortask/memory.md).
PUT	/workspaces/:id/memory	Write the workspace memory file. Body: { content: string }
GET	/workspaces/:id/memory/search	Semantic search over structured memory. Requires ?q. Optional ?limit (1-50, default 5).
GET	/workspaces/:id/memory/entries	List recent memory entries. Optional ?limit (1-100, default 20).
PUT	/workspaces/:id/files/rename	Rename a file. Body: { oldPath, newPath }
DELETE	/workspaces/:id/files/:path	Delete a file or directory.
PUT	/workspaces/:id/files/:path	Write file content. Body: { content: string }
GET	/workspaces/:id/files/:path	Download a file.

---

Credentials

Method	Path	Description
GET	/credentials	List all credential keys (values are not returned).
POST	/credentials	Store a credential. Body: { key, value }
GET	/credentials/:key	Check if a credential exists.
DELETE	/credentials/:key	Delete a credential.

---

Providers

Method	Path	Description
GET	/providers	List available LLM providers with their configuration.
PUT	/providers/default	Set the default provider. Body: { provider: string }

---

Models

Method	Path	Description
GET	/models/:providerId/available	List available models for a provider.
GET	/models/enabled	List all enabled models with pricing info.
POST	/models/enable	Enable a model. Body: { provider, modelId, inputPricePer1m?, outputPricePer1m? }
DELETE	/models/enabled/:id	Disable an enabled model.

---

Skills

Method	Path	Description
GET	/skills	List all skills (bundled and custom).
POST	/skills	Create a custom skill. Body: { name, content }
GET	/skills/:name	Get a skill by name.
PUT	/skills/:name	Update a custom skill. Body: { content }
DELETE	/skills/:name	Remove a custom skill.
POST	/skills/:name/install	Install a skill from a URL.
GET	/skills/:name/file/:filePath	Read a file from a skill directory.
POST	/skills/:name/credentials	Save credentials for a skill.
POST	/skills/:name/oauth/start	Start OAuth flow for a skill.
GET	/skills/oauth/callback	OAuth callback handler.
POST	/skills/:name/oauth/revoke	Revoke OAuth token for a skill.

---

Cron

Method	Path	Description
GET	/cron	List all cron jobs.
GET	/cron/:id	Get a cron job by ID.
POST	/cron	Create a cron job.
PUT	/cron/:id	Update a cron job.
DELETE	/cron/:id	Delete a cron job.
POST	/cron/:id/trigger	Trigger a cron job immediately.
POST	/cron/:id/enable	Enable a cron job.
POST	/cron/:id/disable	Disable a cron job.

---

Templates

Method	Path	Description
GET	/templates	List all prompt templates.
POST	/templates	Create a template.
PUT	/templates/:id	Update a template.
DELETE	/templates/:id	Delete a template.

---

Artifacts

Method	Path	Description
GET	/artifacts	List all artifacts.
GET	/artifacts/:id	Get artifact metadata.
GET	/artifacts/:id?raw	Get raw artifact content.

---

Usage

Method	Path	Description
GET	/usage	Get usage summary for the current spending period.
GET	/usage/history	Get daily usage history. Optional ?days (default 30).

---

Channels

Method	Path	Description
GET	/channels	List channel statuses.
POST	/channels/:id/start	Start a channel adapter.
POST	/channels/:id/stop	Stop a channel adapter.
POST	/channels/:id/credentials	Save channel credentials.
GET	/channels/:id/qr	Get QR code (for WhatsApp).
POST	/channels/:id/trusted-contacts	Update trusted contacts list.

---

Config

Method	Path	Description
GET	/config	Get the current configuration.
PUT	/config	Update configuration. Body: partial config object.

---

Onboarding

Method	Path	Description
GET	/onboarding/status	Check onboarding status.
POST	/onboarding/complete	Mark onboarding as complete.

---

LLM

Method	Path	Description
POST	/llm/complete	Direct LLM completion (used for utility tasks like title generation).

---

Health

Method	Path	Description
GET	/health	Health check. Returns { status, version, ready }.
GET	/updates/check	Check for updates against npm registry.