Skip to main content

​
Todos API

The Todos API provides comprehensive task management with projects, subtasks, priorities, labels, and smart search capabilities.

​
Data Model

​
Todo Object

​
id
string
Unique identifier for the todo
​
user_id
string
User ID who owns the todo
​
title
string
Todo title (1-200 characters)
​
description
string
Optional description (max 2000 characters)
​
priority
string
Priority level: high, medium, low, or none
​
completed
boolean
Whether the todo is completed
​
due_date
string
ISO 8601 due date timestamp (optional)
​
due_date_timezone
string
Timezone for the due date (e.g., “America/New_York”)
​
labels
array
Array of label strings for categorization (max 10)
​
project_id
string
Project ID the todo belongs to (defaults to Inbox)
​
subtasks
array
Array of subtask objects with id, title, and completed fields
​
workflow_id
string
Associated workflow ID (optional)
​
workflow_categories
array
Tool categories from linked workflow steps
​
created_at
string
ISO 8601 creation timestamp
​
updated_at
string
ISO 8601 last update timestamp
​
completed_at
string
ISO 8601 completion timestamp (if completed)

​
Endpoints

​
List Todos

Get todos with filtering, search, and pagination. 
GET /api/v1/todos
​
q
string
Search query (supports text, semantic, and hybrid search)
​
mode
string
default:"hybrid"
Search mode: text, semantic, or hybrid
​
project_id
string
Filter by project ID
​
completed
boolean
Filter by completion status
​
priority
string
Filter by priority: high, medium, low, or none
​
due_today
boolean
Show only todos due today
​
due_this_week
boolean
Show only todos due this week
​
overdue
boolean
Show only overdue todos
​
page
integer
default:"1"
Page number (1-based)
​
per_page
integer
default:"50"
Items per page (max: 100)
​
include_stats
boolean
default:"false"
Include statistics in response
Response
{
  "data": [
    {
      "id": "65f7a8b9c1234567890abcde",
      "title": "Complete API integration",
      "description": "Integrate GAIA API",
      "priority": "high",
      "completed": false,
      "due_date": "2026-02-25T18:00:00Z",
      "labels": ["api", "development"],
      "project_id": "proj_123",
      "subtasks": [],
      "created_at": "2026-02-19T10:00:00Z",
      "updated_at": "2026-02-19T10:00:00Z"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 50,
    "pages": 3,
    "has_next": true,
    "has_prev": false
  },
  "stats": {
    "total": 150,
    "completed": 75,
    "pending": 75,
    "overdue": 10,
    "by_priority": {
      "high": 20,
      "medium": 50,
      "low": 30,
      "none": 50
    },
    "completion_rate": 0.5
  }
}

​
Create Todo

Create a new todo item. 
POST /api/v1/todos
Request
{
  "title": "Complete API integration",
  "description": "Integrate GAIA API into application",
  "priority": "high",
  "due_date": "2026-02-25T18:00:00Z",
  "due_date_timezone": "America/New_York",
  "labels": ["api", "development"],
  "project_id": "proj_123"
}

​
Get Todo

Retrieve a specific todo by ID. 
GET /api/v1/todos/{todo_id}

​
Update Todo

Update a todo (partial updates supported). 
PUT /api/v1/todos/{todo_id}
Request
{
  "completed": true,
  "priority": "medium"
}

​
Delete Todo

Delete a todo. 
DELETE /api/v1/todos/{todo_id}

​
Subtasks

​
Create Subtask

Add a subtask to a todo. 
POST /api/v1/todos/{todo_id}/subtasks
Request
{
  "title": "Write integration tests"
}

​
Update Subtask

Update a subtask. 
PUT /api/v1/todos/{todo_id}/subtasks/{subtask_id}
Request
{
  "title": "Write comprehensive tests",
  "completed": true
}

​
Delete Subtask

Delete a subtask. 
DELETE /api/v1/todos/{todo_id}/subtasks/{subtask_id}

​
Toggle Subtask

Toggle subtask completion status. 
POST /api/v1/todos/{todo_id}/subtasks/{subtask_id}/toggle

​
Bulk Operations

​
Bulk Update

Update multiple todos at once. 
PUT /api/v1/todos/bulk
Request
{
  "todo_ids": ["id1", "id2", "id3"],
  "updates": {
    "completed": true,
    "priority": "high"
  }
}

​
Bulk Delete

Delete multiple todos. 
DELETE /api/v1/todos/bulk
Request
["id1", "id2", "id3"]

​
Bulk Complete

Mark multiple todos as completed. 
POST /api/v1/todos/bulk/complete
Request
["id1", "id2", "id3"]

​
Projects

​
List Projects

Get all projects with todo counts. 
GET /api/v1/projects
Response
[
  {
    "id": "proj_123",
    "name": "Work",
    "description": "Work-related tasks",
    "color": "#FF5733",
    "is_default": false,
    "todo_count": 25,
    "created_at": "2026-01-01T00:00:00Z"
  }
]

​
Create Project

Create a new project. 
POST /api/v1/projects
Request
{
  "name": "Personal",
  "description": "Personal tasks",
  "color": "#3498DB"
}

​
Update Project

Update a project. 
PUT /api/v1/projects/{project_id}

​
Delete Project

Delete a project (todos moved to Inbox). 
DELETE /api/v1/projects/{project_id}

​
Workflows

​
Generate Workflow

Generate a workflow for a todo. 
POST /api/v1/todos/{todo_id}/workflow
Returns immediately with generating status. Listen for workflow.generated WebSocket event.
Response
{
  "status": "generating",
  "todo_id": "todo_123",
  "message": "Workflow generation started. Listen for 'workflow.generated' WebSocket event."
}

​
Get Workflow Status

Get workflow generation status. 
GET /api/v1/todos/{todo_id}/workflow-status
Response
{
  "todo_id": "todo_123",
  "has_workflow": true,
  "is_generating": false,
  "workflow_status": "completed",
  "workflow": {...}
}

​
Next Steps

Calendar API

Manage calendar events

Workflows API

Automate tasks

Build docs developers (and LLMs) love

Get started for freeTalk to us