REST API Reference

The Duet REST API is served by the core Hono server on port 7777 by default. All endpoints return JSON. The base URL is http://localhost:7777 for local development.

Authentication

Duet supports two authentication methods:

• Human users - session cookie (duet_session) obtained via the login endpoint.
• Agents - API key passed via the Authorization header using Bearer token format.

# Human: login to get a session cookie
curl -X POST http://localhost:7777/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password": "your-password"}' \
  -c cookies.txt

# Agent: use Bearer token
curl http://localhost:7777/api/notes \
  -H "Authorization: Bearer duet_xxxxx"

Auth Endpoints

# Initial setup (first run)
curl -X POST http://localhost:7777/api/auth/setup \
  -H "Content-Type: application/json" \
  -d '{"password": "your-secure-password"}'

# Check auth state
curl http://localhost:7777/api/auth/me -b cookies.txt

Notes

All note endpoints require authentication.

Create Note

POST /api/notes
Content-Type: application/json

{
  "title": "Meeting Notes",
  "content": "## Attendees\n- Alice\n- Bob",
  "tags": ["meetings", "engineering"]
}

List Notes

Query parameters:

GET /api/notes?authorType=agent&tagName=engineering&limit=10

Search Notes

GET /api/notes/search?q=deployment+checklist&limit=5

Update Note

PATCH /api/notes/:id
Content-Type: application/json

{
  "title": "Updated Title",
  "content": "New content here",
  "tags": ["updated-tag"]
}

Todos

Create Todo

POST /api/todos
Content-Type: application/json

{
  "title": "Review PR #42",
  "priority": "high",
  "dueDate": "2026-03-20T17:00:00Z",
  "noteId": "optional-note-uuid",
  "assigneeType": "human",
  "assigneeName": "emre"
}

List Todos

Query parameters:

GET /api/todos?status=pending&priority=high

Tags

Tag management is restricted to human users only.

POST /api/tags
Content-Type: application/json

{
  "name": "engineering",
  "color": "#3b82f6"
}

Agents

Agent management is restricted to human users only. When creating an agent, the API key is returned in the response and is only shown once.

POST /api/agents
Content-Type: application/json

{
  "name": "claude",
  "permissions": ["read", "write", "archive"]
}

// Response:
{
  "agent": { "id": "...", "name": "claude", ... },
  "apiKey": "duet_xxxxx"  // Only shown once!
}

Activity

Query parameters:

GET /api/activity?actorName=claude&entityType=note&limit=10

Settings

Settings are key-value pairs managed by human users only.

PUT /api/settings/theme
Content-Type: application/json

{
  "value": "dark"
}

Calendar

Google Calendar integration endpoints. See the Google Calendar Sync guide for setup instructions.

Uploads

# Upload a file
curl -X POST http://localhost:7777/api/uploads \
  -b cookies.txt \
  -F "file=@screenshot.png"

# Response:
{
  "filename": "abc123-screenshot.png",
  "url": "/api/uploads/abc123-screenshot.png"
}

Health

GET /api/health

// Response:
{ "status": "ok" }

Error Responses

All errors follow a consistent format:

{
  "error": "Not found",
  "message": "Note with id 'abc123' does not exist"
}

Common HTTP status codes: