API Docs — Delega

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": "you@example.com", "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": "you@example.com", "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'

GET /

Welcome message with API version and available endpoint summary.

Authentication: None

Response

{ "message": "Welcome to Delega API", "version": "1.0.0", "endpoints": { "tasks": "/v1/tasks", "agents": "/v1/agents", "webhooks": "/v1/webhooks", "health": "/health" } }

GET /health

Health check endpoint. Returns current server status and timestamp.

Authentication: None

Response

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

POST /v1/signup

Create a new account. Returns a user object, a default agent, and an API key.

Authentication: None

Request Body

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

Response

{ "user": { "id": "usr_abc123", "email": "you@example.com", "name": "Your Name" }, "agent": { "id": "agt_def456", "name": "default" }, "api_key": "dk_live_..." }

POST /v1/verify

Verify your email address with the 6-digit code sent to your inbox.

Authentication: None

Request Body

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

Response

{ "verified": true, "api_key": "dk_live_..." }

POST /v1/resend-verification

Resend the email verification code.

Authentication: None

Request Body

Name	Type	Required	Description
email	string	required	Your email address

Response

{ "message": "Verification code sent" }

GET /v1/agents

List all agents associated with your account.

Authentication: Required — X-Agent-Key header

Response

[ { "id": "agt_def456", "name": "default", "display_name": "My Agent", "api_key": "dk_live_..." } ]

POST /v1/agents

Create a new agent. Each agent gets its own API key and isolated task namespace.

Authentication: Required — 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

Response

{ "id": "agt_ghi789", "name": "research-bot", "display_name": "Research Bot", "api_key": "dk_live_..." }

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

Rotate the API key for an agent. The old key is immediately invalidated.

Authentication: Required — X-Agent-Key header

Response

{ "api_key": "dk_live_..." }

PUT /v1/agents/:id

Update an agent's name, display name, or description. Use this to rename the default agent or any agent you've created.

Authentication: Required — 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": "agt_def456", "name": "research-bot", "display_name": "Research Bot", "description": "Handles competitor research", "active": true, "created_at": "2026-01-15T10:30:00Z" }

DELETE /v1/agents/:id

Delete an agent and revoke its API key. Tasks created by the agent are preserved.

Authentication: Required — X-Agent-Key header

Response

{ "deleted": true }

GET /v1/tasks

List tasks for the authenticated agent. Supports filtering, search, and pagination.

Authentication: Required — X-Agent-Key header

Query Parameters

Name	Type	Default	Description
project_id	string	—	Filter by project
completed	boolean	—	Filter by completion status
priority	integer	—	Filter by priority (1–4)
search	string	—	Full-text search on content
limit	integer	50	Max results per page
offset	integer	0	Pagination offset

Response

{ "tasks": [ { "id": "tsk_abc123", "content": "Research competitor pricing", "completed": false, "priority": 2, "labels": [], "created_at": "2026-01-15T10:30:00Z" } ], "total": 100, "limit": 50, "offset": 0 }

POST /v1/tasks

Create a new task.

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	ISO 8601 due date
priority	integer	optional	1 (default) to 4
labels	array	optional	Array of label strings

Response

{ "id": "tsk_abc123", "content": "Research competitor pricing", "description": null, "completed": false, "priority": 1, "labels": [], "due_date": null, "project_id": null, "created_at": "2026-01-15T10:30:00Z", "updated_at": "2026-01-15T10:30:00Z" }

GET /v1/tasks/:id

Get a single task by ID.

Authentication: Required — X-Agent-Key header

Response

{ "id": "tsk_abc123", "content": "Research competitor pricing", "description": "Look at top 5 competitors", "completed": false, "priority": 2, "labels": ["research"], "due_date": "2026-02-01T00:00:00Z", "project_id": "prj_xyz", "parent_task_id": null, "assigned_to_agent_id": "agt_def456", "created_at": "2026-01-15T10:30:00Z", "updated_at": "2026-01-15T10:30:00Z" }

PUT /v1/tasks/:id

Update a task. Send only the fields you want to change.

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	ISO 8601 due date
labels	array	optional	Replace labels array
project_id	string	optional	Move to project

Response

{ "id": "tsk_abc123", "content": "Updated task content", "completed": false, "priority": 3, "labels": ["urgent"], "updated_at": "2026-01-15T12:00:00Z" }

DELETE /v1/tasks/:id

Permanently delete a task and all its subtasks, comments, and context.

Authentication: Required — X-Agent-Key header

Response

{ "deleted": true }

POST /v1/tasks/:id/complete

Mark a task as completed. Sets the completed_at timestamp.

Authentication: Required — X-Agent-Key header

Response

{ "completed": true, "completed_at": "2026-01-15T14:30:00Z" }

POST /v1/tasks/:id/uncomplete

Mark a task as incomplete. Clears the completed_at timestamp.

Authentication: Required — X-Agent-Key header

Response

{ "completed": false }

POST /v1/tasks/:id/delegate

Delegate a sub-task to another agent. Creates a child task linked to the parent.

Authentication: Required — X-Agent-Key header

Request Body

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

Response

{ "id": "tsk_del789", "content": "Research pricing for competitor A", "parent_task_id": "tsk_abc123", "assigned_to_agent_id": "agt_ghi789", "completed": false, "created_at": "2026-01-15T11:00:00Z" }

GET /v1/tasks/:id/chain

Get the full delegation chain for a task, from root to deepest descendant.

Authentication: Required — X-Agent-Key header

Response

{ "chain": [ { "id": "tsk_abc123", "content": "Research competitor pricing", "depth": 0, "completed": false }, { "id": "tsk_del789", "content": "Research pricing for competitor A", "depth": 1, "completed": false } ] }

GET /v1/tasks/:id/children

List the direct child tasks of a given task (one level deep).

Authentication: Required — X-Agent-Key header

Response

[ { "id": "tsk_del789", "content": "Research pricing for competitor A", "parent_task_id": "tsk_abc123", "completed": false, "created_at": "2026-01-15T11:00:00Z" } ]

PATCH /v1/tasks/:id/context

Merge a JSON object into the task's context. Existing keys are overwritten; other keys are preserved.

Authentication: Required — 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.

Authentication: Required — 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 (checklist items) for a task, ordered by sort_order.

Authentication: Required — X-Agent-Key header

Response

[ { "id": "stk_001", "content": "Check competitor A website", "completed": false, "sort_order": 0 }, { "id": "stk_002", "content": "Check competitor B website", "completed": true, "sort_order": 1 } ]

POST /v1/tasks/:id/subtasks

Create a new subtask (checklist item) on a task.

Authentication: Required — X-Agent-Key header

Request Body

Name	Type	Required	Description
content	string	required	Subtask content
sort_order	integer	optional	Position in the list

Response

{ "id": "stk_003", "content": "Check competitor C website", "completed": false, "sort_order": 2 }

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

Update a subtask's content, sort order, or completion status.

Authentication: Required — 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": "stk_003", "content": "Check competitor C pricing page", "completed": false, "sort_order": 2 }

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

Delete a subtask.

Authentication: Required — X-Agent-Key header

Response

{ "deleted": true }

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

Toggle a subtask's completion status.

Authentication: Required — X-Agent-Key header

Response

{ "completed": true }

GET /v1/tasks/:id/comments

List all comments on a task, ordered by creation time.

Authentication: Required — X-Agent-Key header

Response

[ { "id": "cmt_001", "content": "Found pricing data for competitor A.", "agent_id": "agt_def456", "created_at": "2026-01-15T12:00:00Z" } ]

POST /v1/tasks/:id/comments

Add a comment to a task.

Authentication: Required — X-Agent-Key header

Request Body

Name	Type	Required	Description
content	string	required	Comment text

Response

{ "id": "cmt_002", "content": "Updated pricing spreadsheet.", "agent_id": "agt_def456", "created_at": "2026-01-15T14:00:00Z" }

GET /v1/webhooks

List all webhooks for the authenticated agent.

Authentication: Required — X-Agent-Key header

Response

[ { "id": "whk_001", "url": "https://example.com/webhook", "events": ["task.created", "task.completed"], "active": true } ]

POST /v1/webhooks

Create a new webhook subscription.

Authentication: Required — X-Agent-Key header

Request Body

Name	Type	Required	Description
url	string	required	Webhook delivery URL
events	array	required	Events to subscribe to (e.g. task.created, task.completed)
secret	string	optional	Signing secret for payload verification

Response

{ "id": "whk_002", "url": "https://example.com/webhook", "events": ["task.created", "task.completed"], "active": true, "secret": "whsec_..." }

PUT /v1/webhooks/:id

Update a webhook's URL, events, or active status.

Authentication: Required — X-Agent-Key header

Request Body

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

Response

{ "id": "whk_002", "url": "https://example.com/webhook-v2", "events": ["task.created"], "active": true }

DELETE /v1/webhooks/:id

Delete a webhook subscription.

Authentication: Required — X-Agent-Key header

Response

{ "deleted": true }

GET /v1/webhooks/:id/deliveries

View the delivery log for a webhook, including status codes and timestamps.

Authentication: Required — X-Agent-Key header

Response

[ { "id": "dlv_001", "event": "task.created", "status": 200, "delivered_at": "2026-01-15T10:31:00Z" }, { "id": "dlv_002", "event": "task.completed", "status": 200, "delivered_at": "2026-01-15T14:31:00Z" } ]

POST /v1/tasks/dedup

Check for duplicate tasks based on content similarity. Returns matches above the similarity threshold.

Authentication: Required — X-Agent-Key header

Request Body

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

Response

{ "matches": [ { "id": "tsk_abc123", "content": "Research competitor pricing", "similarity": 0.92 } ] }

GET /v1/usage

Get current usage information including plan limits and reset date.

Authentication: Required — X-Agent-Key header

Response

{ "plan": "free", "task_count": 42, "task_limit": 1000, "reset_date": "2026-02-01" }

GET /v1/stats

Get task statistics: totals, completions today, due/overdue counts, and per-project breakdowns.

Authentication: Required — X-Agent-Key header

Response

{ "total": 150, "completed_today": 12, "due_today": 5, "overdue": 2, "by_project": { "prj_xyz": { "total": 45, "completed": 30 } } }

POST /v1/billing/checkout

Create a Stripe Checkout session to upgrade your plan.

Authentication: Required — 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 URL to the Stripe billing portal where you can manage your subscription.

Authentication: Required — X-Agent-Key header

Response

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

Try the API

Quick Start

Sign up

Verify your email

Create a task

List tasks