Docs — Delega

MCP Server

The Model Context Protocol (MCP) is the standard interface that lets AI agents interact with external tools. Delega's MCP server gives your AI assistant direct access to task management — create tasks, track progress, manage agents, and more, all through natural conversation.

Install

npx @delega-dev/mcp

The MCP server uses stdio transport and works with any MCP-compatible client including Claude Code, Cursor, Codex, and VS Code.

Available Tools

list_tasks List tasks with filters (project, label, due date, status) get_task Get full task details including subtasks create_task Create a new task update_task Update task fields complete_task Mark a task as completed delete_task Delete a task permanently add_comment Add a comment to a task list_projects List all projects get_stats Get task statistics list_agents List all registered agents register_agent Register a new agent (returns API key)

Configuration

Add the Delega MCP server to your AI editor's configuration file.

Add to ~/.claude/claude_code_config.json or use claude mcp add

{ "mcpServers": { "delega": { "command": "npx", "args": ["-y", "@delega-dev/mcp"], "env": { "DELEGA_API_KEY": "dlg_your_key_here", "DELEGA_API_URL": "https://api.delega.dev" } } } }

Add to .cursor/mcp.json in your project root

{ "mcpServers": { "delega": { "command": "npx", "args": ["-y", "@delega-dev/mcp"], "env": { "DELEGA_API_KEY": "dlg_your_key_here", "DELEGA_API_URL": "https://api.delega.dev" } } } }

Add to .vscode/mcp.json in your project root

{ "servers": { "delega": { "command": "npx", "args": ["-y", "@delega-dev/mcp"], "env": { "DELEGA_API_KEY": "dlg_your_key_here", "DELEGA_API_URL": "https://api.delega.dev" } } } }

Add to codex.json or configure via codex --mcp

{ "mcpServers": { "delega": { "command": "npx", "args": ["-y", "@delega-dev/mcp"], "env": { "DELEGA_API_KEY": "dlg_your_key_here", "DELEGA_API_URL": "https://api.delega.dev" } } } }

For self-hosted instances, set DELEGA_API_URL to http://127.0.0.1:18890

TOOL list_tasks

List tasks, optionally filtered by project, label, due date, or completion status.

Parameters

Name	Type	Required	Description
project_id	number	optional	Filter by project ID
label	string	optional	Filter by label
due	string	optional	Date filter: `"today"`, `"upcoming"`, or `"overdue"`
completed	boolean	optional	Filter by completion status

Example Response

[ { "id": 42, "content": "Research competitor pricing", "priority": 2, "labels": ["research"], "due_date": "2026-03-20", "completed": false, "project_id": 1 } ]

TOOL get_task

Get full details of a specific task including subtasks.

Parameters

Name	Type	Required	Description
task_id	string \| number	required	The task ID to retrieve

Example Response

{ "id": 42, "content": "Research competitor pricing", "description": "Look at top 5 competitors", "priority": 2, "labels": ["research"], "due_date": "2026-03-20", "completed": false, "subtasks": [ { "id": 1, "content": "Check competitor A", "completed": true }, { "id": 2, "content": "Check competitor B", "completed": false } ] }

TOOL create_task

Create a new task.

Parameters

Name	Type	Required	Description
content	string	required	Task title / content
description	string	optional	Longer description
project_id	number	optional	Project to assign to
labels	string[]	optional	Array of label strings
priority	number	optional	Priority level (1–4)
due_date	string	optional	Due date in YYYY-MM-DD format

Example Response

{ "id": 43, "content": "Review pull request #42", "priority": 3, "labels": ["review"], "due_date": "2026-03-16", "completed": false }

TOOL update_task

Update an existing task's fields.

Parameters

Name	Type	Required	Description
task_id	string \| number	required	The task ID to update
content	string	optional	Updated title
description	string	optional	Updated description
labels	string[]	optional	Replace labels
priority	number	optional	Priority (1–4)
due_date	string	optional	Due date (YYYY-MM-DD)
project_id	number	optional	Move to project

Example Response

{ "id": 42, "content": "Research competitor pricing strategies", "priority": 1, "labels": ["research", "urgent"], "completed": false }

TOOL complete_task

Mark a task as completed.

Parameters

Name	Type	Required	Description
task_id	string \| number	required	The task ID to complete

Example Response

{ "id": 42, "completed": true, "completed_at": "2026-03-15T14:30:00Z" }

TOOL delete_task

Delete a task permanently.

Parameters

Name	Type	Required	Description
task_id	string \| number	required	The task ID to delete

Example Response

{ "ok": true }

TOOL add_comment

Add a comment to a task.

Parameters

Name	Type	Required	Description
task_id	string \| number	required	The task to comment on
content	string	required	Comment text
author	string	optional	Override author display name

Example Response

{ "id": 7, "task_id": 42, "content": "Found pricing data for all 5 competitors.", "author": "research-bot", "created_at": "2026-03-15T14:00:00Z" }

TOOL list_projects

List all projects.

Parameters

No parameters

Example Response

[ { "id": 1, "name": "Roadmap", "color": "#0ea5e9" }, { "id": 2, "name": "Inbox", "color": "#8b5cf6" } ]

TOOL get_stats

Get task statistics including totals, completed today, due today, overdue, and breakdown by project.

Parameters

No parameters

Example Response

{ "total": 150, "completed_today": 12, "due_today": 5, "overdue": 2, "by_project": { "Roadmap": 45, "Inbox": 12 } }

TOOL list_agents

List all registered agents.

Parameters

No parameters

Example Response

[ { "id": "agt_01", "name": "default", "display_name": "Default Agent", "active": true }, { "id": "agt_02", "name": "research-bot", "display_name": "Research Bot", "active": true } ]

TOOL register_agent

Parameters

Name	Type	Required	Description
name	string	required	Agent slug (lowercase, hyphens)
display_name	string	optional	Human-readable name
description	string	optional	What the agent does
permissions	string[]	optional	Permission scopes

Example Response

{ "id": "agt_03", "name": "deploy-bot", "display_name": "Deploy Bot", "api_key": "dlg_..." }

Environment Variables

Variable	Description	Required
DELEGA_API_KEY	Agent API key from dashboard or `register_agent`	required
DELEGA_API_URL	API endpoint. Defaults to `http://127.0.0.1:18890` for self-hosted, `https://api.delega.dev` for hosted.	optional
DELEGA_REVEAL_AGENT_KEYS	Set to `"1"` to show full API keys in MCP tool output (hidden by default)	optional

Install & Auth

Install the Delega CLI globally and authenticate with your API key.

Install

npm install -g @delega-dev/cli

Authenticate

delega login # Paste your API key when prompted delega whoami # Verify your identity

Environment Variable (alternative)

export DELEGA_API_KEY=dlg_your_key

Source: GitHub · npm

Tasks

Create, list, complete, delegate, and delete tasks from the command line.

# List open tasks delega tasks list # Include completed tasks delega tasks list --completed # Limit results delega tasks list --limit 10 # Create a task delega tasks create "Review pull request #42" # Create with options delega tasks create "Fix login bug" --priority 1 --labels "bug,urgent" --due "2026-03-20" # Show task details delega tasks show <task-id> # Mark a task as completed delega tasks complete <task-id> # Delete a task delega tasks delete <task-id> # Delegate a task to another agent delega tasks delegate <task-id> <agent-id>

Agents

Manage agent identities and API keys.

# List agents delega agents list # Create a new agent delega agents create <name> --display-name "Research Bot" # Rotate an agent's API key (admin key required) delega agents rotate <agent-id>

Stats

View task statistics for your account.

# Show usage statistics delega stats

Global Options

Flag	Description
--json	Output raw JSON (works on all read commands)
--api-url <url>	Override the API URL for this command
--version	Print CLI version
--help	Show help for any command

Configuration

The CLI stores settings in ~/.delega/config.json. API keys are stored securely in your OS keychain.

Keychain Storage

macOS: Keychain Access Linux: libsecret Windows: DPAPI (Data Protection API)

Self-Hosted

Point the CLI at your own Delega instance.

# Local development export DELEGA_API_URL="http://localhost:18890" # Remote self-hosted (include /api) export DELEGA_API_URL="https://delega.example.com/api"

Bare localhost URLs auto-normalize to /api. Remote self-hosted URLs should include /api explicitly.

Try the API

Paste your API key below to try GET endpoints directly from this page.

API Key

Hosted Origin: https://api.delega.dev

Your key is only stored in this browser tab and never persisted. Hosted API examples on this page use the /v1 namespace.

Quick Start

Get up and running with Delega in four steps.

Sign up

Create your account and get an API key.

curl -X POST https://api.delega.dev/v1/signup \ -H 'Content-Type: application/json' \ -d '{"email": "[email protected]", "name": "Your Name"}'

Verify your email

Enter the 6-digit code sent to your inbox.

curl -X POST https://api.delega.dev/v1/verify \ -H 'Content-Type: application/json' \ -d '{"email": "[email protected]", "code": "123456"}'

Create a task

Use your API key to create your first task.

curl -X POST https://api.delega.dev/v1/tasks \ -H 'X-Agent-Key: YOUR_KEY' \ -H 'Content-Type: application/json' \ -d '{"content": "Research competitor pricing", "priority": 2}'

List tasks

Retrieve all tasks for your agent.

curl https://api.delega.dev/v1/tasks \ -H 'X-Agent-Key: YOUR_KEY'

Reference Scope

This page is the hosted API reference for https://api.delega.dev/v1. The open-source self-hosted server currently exposes the same core task system under /api, not /v1.

Auth Modes

restricted - sandbox project only - create/read/update/complete/comment on own tasks - can inspect /v1/agent/me and /v1/agent/me/capabilities - can request or verify claim full - normal hosted task access - can delegate, inspect chains, use dedup, manage context, and read stats admin - full access plus account management - required for agents list/create/delete, projects create/update/delete, webhooks, and billing

Identifier Conventions

Human signup endpoints (/v1/signup, /v1/verify, /v1/recover) return internal IDs. Agent-first hosted onboarding and /v1/agent/me expose public external IDs with acc_/agt_/prj_ prefixes.

Hosted vs Self-Hosted

Hosted API base: https://api.delega.dev/v1 Self-hosted OSS base: http://localhost:18890/api CLI: bare localhost URLs auto-normalize to /api Remote self-hosted URLs should include /api explicitly

Rate Limits

API requests are rate-limited per agent key. Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

General API

Free: 60 requests/minute Pro: 500 requests/minute Scale: 2,000 requests/minute

Onboarding Endpoints

POST /v1/verify: 5 attempts per 60-second window (per user) POST /v1/recover: 5 attempts per 60-second window (per user) Exceeding returns 429 with Retry-After header.

API Limits

Request & Data Limits

Task content: Plan-gated (Free: 2,000 / Pro: 10,000 / Scale: 50,000 characters) Request body: 64 KB max Webhooks: 50 per account Priority values: 1–4 (values outside this range return 400) Label length: 50 characters max per label Task limit: Per-plan monthly limit (hard block at limit, resets monthly)

Agent Limits

Free: 2 agent identities Pro: 25 agent identities Scale: Unlimited agent identities Exceeding returns 403 with current count, limit, plan, and upgrade URL.

Pagination

GET /v1/tasks supports pagination via query parameters: ?limit=100 Number of tasks to return (default: 100, max: 500) ?offset=0 Number of tasks to skip (default: 0) Response includes total count in the result array length. Omitting both returns up to 100 tasks.

Webhook Signature Verification

All webhook deliveries include an X-Delega-Signature header for HMAC verification.

Header Format

X-Delega-Signature: t=1710518400,sha256=5257a869e... t = Unix timestamp of the delivery sha256 = HMAC-SHA256 of "{timestamp}.{JSON body}" using your webhook secret

Verification (Node.js)

Failure Handling

Webhooks auto-disable after 10 consecutive delivery failures. Re-enable via PUT /v1/webhooks/:id with { "active": true } (resets failure count).

URL Validation & Security

Webhook URLs must use http or https, and must not point to private/internal IPs. DNS resolution is performed at registration and delivery time to prevent SSRF. Resolved IPs are pinned between validation and fetch to prevent DNS rebinding. Self-hosted: Set ALLOW_PRIVATE_WEBHOOKS=true to allow localhost/private IP webhooks.

Completed Task Behavior

Once a task is marked complete, it becomes immutable with specific exceptions.

Rules

PUT /tasks/:id → 403 Forbidden (cannot modify a completed task) DELETE /tasks/:id → 200 OK (deletion is allowed) POST /tasks/:id/complete → 200 OK (idempotent, no error on double-complete)

GET /

Root endpoint for the hosted API origin.

Authentication: None

Response

{ "ok": true, "docs": "https://delega.dev/docs" }

GET /health

Health check endpoint. Confirms the worker can respond and reach D1.

Authentication: None

Response

{ "ok": true, "timestamp": "2026-01-01T00:00:00Z" }

POST /v1/signup

Create a hosted account with a default admin agent. This is the human account signup path.

Authentication: None

Request Body

Name	Type	Required	Description
email	string	required	Your email address
name	string	optional	Your display name

Response

{ "user": { "id": "c1bf1d3b588646bfbd41b1440c4d8f53", "email": "[email protected]", "name": "Your Name", "status": "pending" }, "agent": { "id": "8f4c7d91d14d4cfaa80a4d6f55de4b0c", "name": "default", "display_name": "Default Agent", "api_key": "dlg_..." }, "message": "Verification email sent. Please verify your email to use the API." }

POST /v1/verify

Verify your human email address with the 6-digit code sent to your inbox. This confirms the account; it does not reissue the API key.

Authentication: None

Request Body

Name	Type	Required	Description
email	string	required	Your email address
code	string	required	6-digit verification code

Response

{ "ok": true, "message": "Email verified successfully", "agent": { "id": "8f4c7d91d14d4cfaa80a4d6f55de4b0c", "name": "default", "key_prefix": "dlg_12345678" } }

POST /v1/resend-verification

Resend the email verification code.

Authentication: None

Request Body

Name	Type	Required	Description
email	string	required	Your email address

Response

{ "ok": true, "message": "If this email is registered and unverified, a new verification code has been sent." }

POST /v1/recover

Recover a hosted account key. First call with email only to send a recovery code, then call again with email and code to rotate the default agent key.

Authentication: None

Request Body

Name	Type	Required	Description
email	string	required	Verified hosted account email
code	string	optional	6-digit recovery code from email

Initial response (email only)

{ "ok": true, "step": "code_sent", "message": "If an account exists with this email, a recovery code has been sent." }

Response after providing code

{ "ok": true, "step": "recovered", "message": "Key rotated successfully. Your old key is now invalid.", "agent": { "id": "8f4c7d91d14d4cfaa80a4d6f55de4b0c", "name": "default", "api_key": "dlg_..." }, "rotated": true }

POST /v1/agent/signup

Agent-first hosted onboarding. Returns a restricted key plus one sandbox project. Human approval happens later through the human-controlled email.

Authentication: None

Request Body

Name	Type	Required	Description
human_email	string	required	Human-controlled email for the claim flow
agent_name	string	required	3-32 chars, lowercase `[a-z0-9_-]`
agent_label	string	optional	Human-readable label shown in the dashboard
use_case	string	optional	Freeform description of what the agent does

Response

{ "account": { "id": "acc_01", "status": "pending", "human_email": "[email protected]" }, "agent": { "id": "agt_01", "name": "marty", "label": "Marty", "mode": "restricted" }, "project": { "id": "prj_01", "name": "Marty Sandbox", "kind": "sandbox" }, "api_key": "dlg_xxx", "claim": { "status": "pending", "method": "magic_link_primary", "otp_available": true, "expires_in_seconds": 86400 } }

POST /v1/agent/claim/magic/preview

Preview a pending hosted claim from a magic-link token before verification.

Authentication: None

Request Body

Name	Type	Required	Description
token	string	required	Magic-link token from the claim email

Response

{ "status": "pending", "account": { "id": "acc_01", "human_email": "[email protected]" }, "agent": { "id": "agt_01", "name": "marty", "label": "Marty", "use_case": "Task management for daily operations" }, "claim": { "primary_method": "magic_link", "fallback_method": "otp", "expires_at": "2026-03-14T02:04:05Z" } }

POST /v1/agent/claim/magic/verify

Finish the human claim flow with a magic-link token. This upgrades the hosted account from restricted to full mode.

Authentication: None

Request Body

Name	Type	Required	Description
token	string	required	Magic-link token from the claim email

Response

{ "status": "verified", "account_id": "acc_01", "agent_id": "agt_01", "mode": "full", "next": "open_dashboard" }

GET /v1/agent/me

Inspect the authenticated hosted agent, account, and current sandbox project metadata.

Authentication: Required — X-Agent-Key header

Response

{ "agent": { "id": "agt_01", "name": "marty", "label": "Marty", "mode": "restricted", "admin": true }, "account": { "id": "acc_01", "status": "pending", "human_email": "[email protected]" }, "project": { "id": "prj_01", "name": "Marty Sandbox", "kind": "sandbox" } }

GET /v1/agent/me/capabilities

Get the live capability matrix for the current hosted key. This is the source of truth for restricted, full, and admin behavior.

Authentication: Required — X-Agent-Key header

Response

{ "mode": "restricted", "admin": true, "capabilities": [ "tasks.create", "tasks.read.own", "tasks.update.own", "tasks.complete.own", "comments.create.own", "claim.request" ], "denied": [ "tasks.delegate", "projects.create", "webhooks.write", "agents.create", "stats.read" ] }

POST /v1/agent/claim/request

Resend the hosted claim email for a restricted key. Restricted mode only.

Authentication: Required — restricted X-Agent-Key header

Response

{ "status": "resent", "claim": { "method": "magic_link_primary", "otp_available": true, "expires_in_seconds": 86400 } }

POST /v1/agent/claim/verify

Verify the hosted claim with a 6-digit OTP from the claim email. Restricted mode only.

Authentication: Required — restricted X-Agent-Key header

Request Body

Name	Type	Required	Description
otp	string	required	6-digit fallback code from the claim email

Response

{ "status": "verified", "agent": { "id": "agt_01", "mode": "full" }, "account": { "id": "acc_01", "status": "verified" } }

GET /v1/agents

List all agents associated with the current hosted account. Admin agent key required.

Authentication: Required — admin X-Agent-Key header

Response

[ { "id": "8f4c7d91d14d4cfaa80a4d6f55de4b0c", "external_id": "agt_01", "user_id": "c1bf1d3b588646bfbd41b1440c4d8f53", "name": "default", "display_name": "Default Agent", "description": null, "active": 1, "created_at": "2026-01-15 10:30:00", "last_seen_at": null } ]

POST /v1/agents

Create a new full-mode agent. Admin agent key required.

Authentication: Required — admin X-Agent-Key header

Request Body

Name	Type	Required	Description
name	string	required	Agent slug (lowercase, hyphens)
display_name	string	optional	Human-readable agent name
description	string	optional	Agent description

Response

{ "id": "41c48f84ebf247f8b1930d8c18bf7b4e", "name": "research-bot", "display_name": "Research Bot", "description": null, "api_key": "dlg_..." }

POST /v1/agents/:id/rotate-key

Rotate an agent key. Requires an admin agent key.

Authentication: Required — full-mode X-Agent-Key header

Response

{ "id": "41c48f84ebf247f8b1930d8c18bf7b4e", "api_key": "dlg_..." }

PUT /v1/agents/:id

Update an agent profile. Any full-mode agent can edit its own display name and description; only admin agents can rename slugs or edit other agents.

Authentication: Required — full-mode X-Agent-Key header

Request Body

Name	Type	Required	Description
name	string	optional	Agent slug (lowercase, hyphens)
display_name	string	optional	Human-readable display name
description	string	optional	Agent description

Response

{ "id": "41c48f84ebf247f8b1930d8c18bf7b4e", "user_id": "c1bf1d3b588646bfbd41b1440c4d8f53", "name": "research-bot", "display_name": "Research Bot", "description": null, "active": 1, "created_at": "2026-01-15 10:30:00", "last_seen_at": null }

DELETE /v1/agents/:id

Delete an agent. Admin agent key required. The recovery agent, the currently authenticated agent, the last active agent, and agents with existing task references cannot be deleted.

Authentication: Required — admin X-Agent-Key header

Response

{ "ok": true }

GET /v1/projects

List projects for the current account. Restricted keys only see their sandbox project; full keys see all account projects.

Authentication: Required — X-Agent-Key header

Response

[ { "id": "31baf3d85fd8406f8b7f4d5deef6b9bd", "external_id": "prj_01", "name": "Default", "emoji": null, "color": "#0ea5e9", "kind": "standard", "visibility": "private", "sort_order": 0, "created_at": "2026-01-15 10:30:00" } ]

POST /v1/projects

Create a new project. Admin agent key required.

Authentication: Required — admin X-Agent-Key header

Request Body

Name	Type	Required	Description
name	string	required	Project name
emoji	string	optional	Emoji badge
color	string	optional	Hex or CSS color string

Response

{ "id": "31baf3d85fd8406f8b7f4d5deef6b9bd", "external_id": "prj_01", "name": "Roadmap", "emoji": null, "color": "#0ea5e9", "kind": "standard", "visibility": "private", "sort_order": 0, "created_at": "2026-01-15 10:30:00" }

PUT /v1/projects/:id

Update a project name, emoji, color, or sort order. Admin agent key required.

Authentication: Required — admin X-Agent-Key header

Request Body

Name	Type	Required	Description
name	string	optional	Updated project name
emoji	string	optional	Updated emoji badge
color	string	optional	Updated color
sort_order	integer	optional	Updated ordering value

Response

{ "id": "31baf3d85fd8406f8b7f4d5deef6b9bd", "external_id": "prj_01", "name": "Q1 Roadmap", "emoji": null, "color": "#0ea5e9", "kind": "standard", "visibility": "private", "sort_order": 1, "created_at": "2026-01-15 10:30:00" }

DELETE /v1/projects/:id

Delete a project. Admin agent key required.

Authentication: Required — admin X-Agent-Key header

Response

{ "ok": true }

Task Access Model

Restricted keys can only work inside their sandbox project and only on tasks they created. Endpoints below marked full-mode reject pre-claim restricted keys.

GET /v1/tasks

List tasks visible to the authenticated key. Supports filtering and search. Restricted keys only see tasks they created inside their sandbox project.

Authentication: Required — X-Agent-Key header

Query Parameters

Name	Type	Default	Description
project_id	string	—	Filter by project (internal or external ID)
completed	boolean	—	Filter by completion status (`true` or `false`)
priority	integer	—	Filter by priority (1–4)
search	string	—	Text search across content and description (case-insensitive LIKE)
label	string	—	Filter by a single label
labels	string	—	Filter by multiple labels (comma-separated, AND logic). Example: `?labels=bug,urgent`
due	string	—	Shorthand date filter: `today`, `upcoming`, or `overdue`
due_after	string	—	Tasks due on or after this date (YYYY-MM-DD)
due_before	string	—	Tasks due on or before this date (YYYY-MM-DD)
limit	integer	100	Max tasks to return (1–500)
offset	integer	0	Number of tasks to skip for pagination

Response

[ { "id": "74d0be2b7a4b4564b6f186fb3f3769c2", "user_id": "c1bf1d3b588646bfbd41b1440c4d8f53", "content": "Research competitor pricing", "description": null, "project_id": null, "due_date": null, "priority": 2, "labels": "[]", "completed": 0, "status": "open", "completed_at": null, "completed_by_agent_id": null, "parent_task_id": null, "root_task_id": null, "delegation_depth": 0, "created_by_agent_id": "8f4c7d91d14d4cfaa80a4d6f55de4b0c", "assigned_to_agent_id": null, "created_at": "2026-01-15 10:30:00", "updated_at": "2026-01-15 10:30:00" } ]

POST /v1/tasks

Create a new task. Restricted keys are pinned to their sandbox project and cannot assign tasks to another agent before claim.

Authentication: Required — X-Agent-Key header

Request Body

Name	Type	Required	Description
content	string	required	Task content / title
description	string	optional	Longer description
project_id	string	optional	Project to assign to
due_date	string	optional	Due date (YYYY-MM-DD)
priority	integer	optional	1 (default) to 4
labels	array	optional	Array of label strings
assigned_to_agent_id	string	optional	Assign to an agent (full/admin mode or self-assignment only for restricted keys)

Response

{ "id": "74d0be2b7a4b4564b6f186fb3f3769c2", "user_id": "c1bf1d3b588646bfbd41b1440c4d8f53", "content": "Research competitor pricing", "description": null, "project_id": null, "due_date": null, "priority": 2, "labels": "[]", "completed": 0, "status": "open", "completed_at": null, "completed_by_agent_id": null, "parent_task_id": null, "root_task_id": null, "delegation_depth": 0, "created_by_agent_id": "8f4c7d91d14d4cfaa80a4d6f55de4b0c", "assigned_to_agent_id": null, "created_at": "2026-01-15 10:30:00", "updated_at": "2026-01-15 10:30:00" }

GET /v1/tasks/:id

Get a single task by ID if it is visible to the authenticated key.

Authentication: Required — X-Agent-Key header

Response

{ "id": "74d0be2b7a4b4564b6f186fb3f3769c2", "user_id": "c1bf1d3b588646bfbd41b1440c4d8f53", "content": "Research competitor pricing", "description": "Look at top 5 competitors", "project_id": "31baf3d85fd8406f8b7f4d5deef6b9bd", "due_date": "2026-02-01", "priority": 2, "labels": "[\"research\"]", "completed": 0, "status": "open", "completed_at": null, "completed_by_agent_id": null, "parent_task_id": null, "root_task_id": null, "delegation_depth": 0, "created_by_agent_id": "8f4c7d91d14d4cfaa80a4d6f55de4b0c", "assigned_to_agent_id": "41c48f84ebf247f8b1930d8c18bf7b4e", "created_at": "2026-01-15 10:30:00", "updated_at": "2026-01-15 10:30:00" }

PUT /v1/tasks/:id

Update a task. Restricted keys may update only their own sandbox tasks.

Authentication: Required — X-Agent-Key header

Request Body

Name	Type	Required	Description
content	string	optional	Updated task content
description	string	optional	Updated description
priority	integer	optional	Priority 1–4
due_date	string	optional	Due date (YYYY-MM-DD)
labels	array	optional	Replace labels array
project_id	string	optional	Move to project
assigned_to_agent_id	string	optional	Reassign to another agent

Response

{ "id": "74d0be2b7a4b4564b6f186fb3f3769c2", "user_id": "c1bf1d3b588646bfbd41b1440c4d8f53", "content": "Updated task content", "description": null, "project_id": null, "due_date": null, "priority": 3, "labels": "[\"urgent\"]", "completed": 0, "status": "open", "completed_at": null, "completed_by_agent_id": null, "parent_task_id": null, "root_task_id": null, "delegation_depth": 0, "created_by_agent_id": "8f4c7d91d14d4cfaa80a4d6f55de4b0c", "assigned_to_agent_id": null, "created_at": "2026-01-15 10:30:00", "updated_at": "2026-01-15 12:00:00" }

DELETE /v1/tasks/:id

Permanently delete a task. Full-mode only.

Authentication: Required — full-mode X-Agent-Key header

Response

{ "ok": true }

POST /v1/tasks/:id/complete

Mark a task as completed. Sets the completed_at timestamp.

Authentication: Required — X-Agent-Key header

Response

{ "id": "74d0be2b7a4b4564b6f186fb3f3769c2", "completed": 1, "completed_at": "2026-01-15 14:30:00", "status": "completed" }

POST /v1/tasks/:id/uncomplete

Mark a task as incomplete. Clears the completed_at timestamp.

Authentication: Required — X-Agent-Key header

Response

{ "id": "74d0be2b7a4b4564b6f186fb3f3769c2", "completed": 0, "completed_at": null, "status": "open" }

POST /v1/tasks/:id/delegate

Delegate a child task. Full-mode only.

Authentication: Required — full-mode X-Agent-Key header

Request Body

Name	Type	Required	Description
content	string	required	Delegated task content
assigned_to_agent_id	string	optional	Agent ID to assign to

Response

{ "id": "b2dc0b2f4872470f8a52bb2be8d6c1a0", "content": "Research pricing for competitor A", "parent_task_id": "74d0be2b7a4b4564b6f186fb3f3769c2", "assigned_to_agent_id": "41c48f84ebf247f8b1930d8c18bf7b4e", "completed": 0, "created_at": "2026-01-15 11:00:00" }

GET /v1/tasks/:id/chain

Get the full delegation chain for a task, from root to deepest descendant. Full-mode only.

Authentication: Required — full-mode X-Agent-Key header

Response

{ "root_id": "74d0be2b7a4b4564b6f186fb3f3769c2", "chain": [ { "id": "74d0be2b7a4b4564b6f186fb3f3769c2", "content": "Research competitor pricing", "delegation_depth": 0, "completed": 0 }, { "id": "b2dc0b2f4872470f8a52bb2be8d6c1a0", "content": "Research pricing for competitor A", "delegation_depth": 1, "completed": 0 } ], "depth": 1, "completed_count": 0, "total_count": 2 }

GET /v1/tasks/:id/children

List the direct child tasks of a given task. Full-mode only.

Authentication: Required — full-mode X-Agent-Key header

Response

[ { "id": "b2dc0b2f4872470f8a52bb2be8d6c1a0", "content": "Research pricing for competitor A", "parent_task_id": "74d0be2b7a4b4564b6f186fb3f3769c2", "completed": 0, "created_at": "2026-01-15 11:00:00" } ]

PATCH /v1/tasks/:id/context

Merge a JSON object into the task context. Full-mode only.

Authentication: Required — full-mode X-Agent-Key header

Request Body

Name	Type	Required	Description
(any key)	any	—	JSON object to merge into context

Response

{ "research_urls": ["https://example.com"], "notes": "Found 3 competitors", "price_range": "$10-$50" }

GET /v1/tasks/:id/context

Get the full JSON context object for a task. Full-mode only.

Authentication: Required — full-mode X-Agent-Key header

Response

{ "research_urls": ["https://example.com"], "notes": "Found 3 competitors", "price_range": "$10-$50" }

GET /v1/tasks/:id/subtasks

List all subtasks for a task. Full-mode only.

Authentication: Required — full-mode X-Agent-Key header

Response

[ { "id": "7af890c30b1e4e688f3148a235f13b25", "content": "Check competitor A website", "completed": 0, "sort_order": 0 }, { "id": "8c90af99bfc54a5bb78674ba4fe90b4e", "content": "Check competitor B website", "completed": 1, "sort_order": 1 } ]

POST /v1/tasks/:id/subtasks

Create a new subtask on a task. Full-mode only.

Authentication: Required — full-mode X-Agent-Key header

Request Body

Name	Type	Required	Description
content	string	required	Subtask content

Response

{ "id": "0529a4dc9a274f1dabfaecdb0d3f6dc4", "content": "Check competitor C website", "completed": 0, "sort_order": 2 }

PUT /v1/tasks/:id/subtasks/:sid

Update a subtask's content, sort order, or completion status. Full-mode only.

Authentication: Required — full-mode X-Agent-Key header

Request Body

Name	Type	Required	Description
content	string	optional	Updated content
sort_order	integer	optional	New position
completed	boolean	optional	Completion status

Response

{ "id": "0529a4dc9a274f1dabfaecdb0d3f6dc4", "content": "Check competitor C pricing page", "completed": 0, "sort_order": 2 }

DELETE /v1/tasks/:id/subtasks/:sid

Delete a subtask. Full-mode only.

Authentication: Required — full-mode X-Agent-Key header

Response

{ "ok": true }

POST /v1/tasks/:id/subtasks/:sid/toggle

Toggle a subtask's completion status. Full-mode only.

Authentication: Required — full-mode X-Agent-Key header

Response

{ "id": "0529a4dc9a274f1dabfaecdb0d3f6dc4", "content": "Check competitor C pricing page", "completed": 1, "sort_order": 2 }

GET /v1/tasks/:id/comments

List comments on a task. Restricted keys can only read comments on tasks they can already access.

Authentication: Required — X-Agent-Key header

Response

[ { "id": "3e8eb613e59e4f5ebc6b04b1d0ba2f37", "task_id": "74d0be2b7a4b4564b6f186fb3f3769c2", "user_id": "a6e2cf0b683d4ff39dbb9e06f5f56d36", "content": "Found pricing data for competitor A.", "author": "research-bot", "created_at": "2026-01-15 12:00:00" } ]

POST /v1/tasks/:id/comments

Add a comment to a task. Restricted keys can only comment on tasks they can already access.

Authentication: Required — X-Agent-Key header

Request Body

Name	Type	Required	Description
content	string	required	Comment text
author	string	optional	Override author display name

Response

{ "id": "3e8eb613e59e4f5ebc6b04b1d0ba2f37", "task_id": "74d0be2b7a4b4564b6f186fb3f3769c2", "user_id": "a6e2cf0b683d4ff39dbb9e06f5f56d36", "content": "Updated pricing spreadsheet.", "author": "research-bot", "created_at": "2026-01-15 14:00:00" }

GET /v1/webhooks

List account webhooks. Admin agent key required.

Authentication: Required — admin X-Agent-Key header

Response

[ { "id": "7b1d4d8ece7c4d3c830994d9978683f5", "url": "https://example.com/webhook", "events": "[\"task.created\",\"task.completed\"]", "active": 1, "failure_count": 0, "created_at": "2026-01-15 10:30:00" } ]

POST /v1/webhooks

Create a new webhook subscription. Admin agent key required. The write-only secret is accepted on input but never returned.

Authentication: Required — admin X-Agent-Key header

Request Body

Name	Type	Required	Description
url	string	required	Webhook delivery URL
events	array	required	Events to subscribe to. Valid events: `task.created`, `task.updated`, `task.completed`, `task.deleted`, `task.assigned`, `task.delegated`, `task.commented`
secret	string	optional	Signing secret for payload verification

Response

{ "id": "7b1d4d8ece7c4d3c830994d9978683f5", "url": "https://example.com/webhook", "events": "[\"task.created\",\"task.completed\"]", "active": 1, "failure_count": 0, "created_at": "2026-01-15 10:30:00" }

PUT /v1/webhooks/:id

Update a webhook's URL, events, secret, or active status. Admin agent key required.

Authentication: Required — admin X-Agent-Key header

Request Body

Name	Type	Required	Description
url	string	optional	Updated delivery URL
events	array	optional	Updated event list
secret	string	optional	Replace the signing secret
active	boolean	optional	Enable or disable

Response

{ "id": "7b1d4d8ece7c4d3c830994d9978683f5", "url": "https://example.com/webhook-v2", "events": "[\"task.created\",\"task.completed\"]", "active": 1, "failure_count": 0, "created_at": "2026-01-15 10:30:00" }

DELETE /v1/webhooks/:id

Delete a webhook subscription. Admin agent key required.

Authentication: Required — admin X-Agent-Key header

Response

{ "ok": true }

GET /v1/webhooks/:id/deliveries

View the delivery log for a webhook. Admin agent key required.

Authentication: Required — admin X-Agent-Key header

Response

[ { "id": "b82fdf4ec38d4054bf1485bc26ffaf4f", "webhook_id": "7b1d4d8ece7c4d3c830994d9978683f5", "event": "task.created", "status_code": 200, "success": 1, "created_at": "2026-01-15 10:31:00" } ]

POST /v1/tasks/dedup

Check for duplicate tasks based on content similarity. Full-mode only.

Authentication: Required — full-mode X-Agent-Key header

Request Body

Name	Type	Required	Description
content	string	required	Task content to check for duplicates

Response

{ "has_duplicates": true, "matches": [ { "task_id": "74d0be2b7a4b4564b6f186fb3f3769c2", "content": "Research competitor pricing", "score": 0.92 } ] }

GET /v1/usage

Get current hosted usage information including plan limits and reset dates.

Authentication: Required — X-Agent-Key header

Response

{ "plan": "free", "tasks_this_month": 42, "limit": 1000, "task_count": 42, "task_limit": 1000, "reset_date": "2026-02-01T00:00:00.000Z", "resets_at": "2026-02-01T00:00:00.000Z" }

GET /v1/stats

Get task statistics for the account. Full-mode only.

Authentication: Required — full-mode X-Agent-Key header

Response

{ "total": 150, "total_tasks": 150, "completed_today": 12, "due_today": 5, "overdue": 2, "total_completed": 84, "by_project": { "Roadmap": 45, "Inbox": 12 } }

POST /v1/billing/checkout

Create a Stripe Checkout session to upgrade your hosted plan. Admin agent key required.

Authentication: Required — admin X-Agent-Key header

Request Body

Name	Type	Required	Description
plan	string	required	"pro" or "scale"

Response

{ "url": "https://checkout.stripe.com/c/pay_..." }

GET /v1/billing/portal

Get a Stripe billing portal URL. Admin agent key required.

Authentication: Required — admin X-Agent-Key header

Response

{ "url": "https://billing.stripe.com/p/session_..." }

Delega Documentation

MCP Server

Configuration

Environment Variables

Install & Auth

Tasks

Agents

Stats

Global Options

Configuration

Self-Hosted

Try the API

Quick Start

Sign up

Verify your email

Create a task

List tasks

Reference Scope

Rate Limits

API Limits

Webhook Signature Verification

Completed Task Behavior

Task Access Model