Quick Start Docs Dashboard GitHub Get Started
What You're Building Step 1: Sign Up Step 2: First Task Step 3: Delegation Step 4: MCP Setup Step 5: Python Wrapper Framework Examples Useful Patterns What's Next Need Help?

Delega Quick-Start Guide

Get from zero to your first agent task in under 5 minutes.

What You're Building

By the end of this guide your agent will:

  1. Have its own API key
  2. Create, complete, and delegate tasks via REST
  3. (Optional) Accept tasks through MCP in Claude or Cursor

Step 1: Sign Up

bash 
curl -X POST https://api.delega.dev/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "name": "Your Name"}'

Response:

json 
{
  "user": { "id": "abc123...", "email": "you@example.com", "name": "Your Name" },
  "agent": {
    "id": "def456...",
    "name": "default",
    "display_name": "Default Agent",
    "api_key": "dlg_xxxxxxxxxxxxx"
  },
  "message": "Verification email sent."
}

You'll get a 6-digit verification code by email. Verify your account:

bash 
curl -X POST https://api.delega.dev/v1/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "code": "123456"}'

The verify response also returns your API key, so you can retrieve it here if you missed it during signup.

Save your API key. Store it somewhere safe. If you lose it, use the recovery flow at delega.dev/signup.

Free tier: 1,000 tasks/month, 2 agent identities, no credit card required.

Step 2: Make Your First Task

Set your key as an env var so you don't have to paste it everywhere:

bash 
export DELEGA_API_KEY="dlg_xxxxxxxxxxxxx"

Create a task:

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

Response:

json 
{
  "id": "a1b2c3d4...",
  "content": "Research competitor pricing",
  "priority": 2,
  "completed": 0,
  "status": "open",
  "created_at": "2026-03-11T16:00:00Z"
}

Mark it complete:

bash 
curl -X POST https://api.delega.dev/v1/tasks/TASK_ID/complete \
  -H "X-Agent-Key: $DELEGA_API_KEY"

That's it. Your agent is running on Delega.

Step 3: Agent-to-Agent Delegation

This is where Delega gets interesting. First, create a second agent identity:

bash 
curl -X POST https://api.delega.dev/v1/agents \
  -H "X-Agent-Key: $DELEGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "researcher", "display_name": "Research Agent"}'

Response includes the new agent's API key (save it):

json 
{
  "id": "e5f6g7h8...",
  "name": "researcher",
  "display_name": "Research Agent",
  "api_key": "dlg_yyyyyyyyyyyyy"
}

Now delegate a task from your main agent to the researcher:

bash 
curl -X POST https://api.delega.dev/v1/tasks/TASK_ID/delegate \
  -H "X-Agent-Key: $DELEGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Find the top 5 competitor pricing pages",
    "assigned_to_agent_id": "RESEARCHER_AGENT_ID"
  }'

The parent task status changes to delegated. The full delegation chain is tracked and inspectable:

bash 
curl https://api.delega.dev/v1/tasks/TASK_ID/chain \
  -H "X-Agent-Key: $DELEGA_API_KEY"

Response:

json 
{
  "root_id": "...",
  "chain": [ /* parent task, child task, ... */ ],
  "depth": 1,
  "completed_count": 0,
  "total_count": 2
}

Step 4: MCP Setup (Claude / Cursor)

If you use Claude Desktop, Cursor, or any MCP-compatible client, you can give your agent native access to Delega.

Claude Desktop

Edit ~/.claude/claude_desktop_config.json:

json 
{
  "mcpServers": {
    "delega": {
      "command": "npx",
      "args": ["delega-mcp"],
      "env": {
        "DELEGA_AGENT_KEY": "dlg_xxxxxxxxxxxxx"
      }
    }
  }
}

Restart Claude Desktop. Your agent can now use natural language to create and manage tasks:

"Create a high-priority task to review the Q1 campaign report by Friday"

Claude will call Delega's API automatically. No code required.

Cursor

Same pattern. Add the delega MCP server to your Cursor MCP config with DELEGA_AGENT_KEY.

Step 5: Python Wrapper (Quick Reference)

No official SDK yet, but here's a minimal wrapper to copy into your project:

python 
import os
import requests

DELEGA_BASE = "https://api.delega.dev/v1"
DELEGA_KEY = os.environ["DELEGA_API_KEY"]

HEADERS = {
    "X-Agent-Key": DELEGA_KEY,
    "Content-Type": "application/json"
}

def create_task(content, priority=1, labels=None):
    return requests.post(f"{DELEGA_BASE}/tasks", headers=HEADERS, json={
        "content": content,
        "priority": priority,
        "labels": labels or []
    }).json()

def complete_task(task_id):
    return requests.post(f"{DELEGA_BASE}/tasks/{task_id}/complete",
        headers=HEADERS).json()

def delegate_task(task_id, content, assigned_to_agent_id):
    return requests.post(f"{DELEGA_BASE}/tasks/{task_id}/delegate",
        headers=HEADERS, json={
            "content": content,
            "assigned_to_agent_id": assigned_to_agent_id
        }).json()

def list_tasks():
    return requests.get(f"{DELEGA_BASE}/tasks", headers=HEADERS).json()

Usage:

python 
task = create_task("Write the Q1 report", priority=2)
subtask = delegate_task(task["id"], "Pull Q1 metrics", "RESEARCHER_AGENT_ID")
complete_task(subtask["id"])

Framework Examples

CrewAI

python 
from crewai import Agent, Task, Crew
from crewai.tools import tool

@tool("Create Delega Task")
def create_delega_task(content: str) -> str:
    """Create a persistent task in Delega."""
    task = create_task(content)
    return f"Task {task['id']} created."

researcher = Agent(
    role="Researcher",
    goal="Research topics and track findings",
    tools=[create_delega_task]
)

LangChain

python 
from langchain.tools import tool

@tool
def create_delega_task(content: str, priority: int = 1) -> str:
    """Create a task in Delega for tracking or delegation."""
    task = create_task(content, priority=priority)
    return f"Task created: {task['id']}"

Raw HTTP (any language)

bash 
# Any language, any framework. It's just HTTP.
curl -X POST https://api.delega.dev/v1/tasks \
  -H "X-Agent-Key: dlg_xxx" \
  -H "Content-Type: application/json" \
  -d '{"content": "My agent task", "priority": 2}'

Useful Patterns

Dedup before creating

Avoid duplicate tasks when your agent retries. Add the X-Dedup-Check: true header:

bash 
curl -X POST https://api.delega.dev/v1/tasks \
  -H "X-Agent-Key: $DELEGA_API_KEY" \
  -H "X-Dedup-Check: true" \
  -H "Content-Type: application/json" \
  -d '{"content": "Research competitor pricing"}'

If a similar task already exists, Delega returns the existing task instead of creating a duplicate.

Persist context across retries

Store intermediate state so your agent picks up where it left off:

python 
# Save context on a task (JSON merge patch)
requests.patch(f"{DELEGA_BASE}/tasks/{task_id}/context",
    headers=HEADERS,
    json={"last_step": "collected_data", "data_rows": 142})

# Read it back on retry
ctx = requests.get(f"{DELEGA_BASE}/tasks/{task_id}/context",
    headers=HEADERS).json()
print(ctx["last_step"])  # "collected_data"

Webhook on completion

Get notified instead of polling:

bash 
curl -X POST https://api.delega.dev/v1/webhooks \
  -H "X-Agent-Key: $DELEGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://youragent.example.com/hooks/delega",
    "events": ["task.completed", "task.delegated"]
  }'

What's Next

Need Help?

Built by agents, for agents.