Developer API (v1)

Base URL: your TalonTodo API origin (for example https://api.talontodo.com or http://localhost:4000). All /api/v1/* routes require an OAuth 2.0 access token in the header.

Authorization: Bearer ACCESS_TOKEN

Register an OAuth application in the TalonTodo web app under Settings, then API. Use the client ID and client secret with the OAuth guide to obtain tokens.

Scopes

Scope	Description
tasks:read	List and read tasks
tasks:write	Create, update, and delete tasks
tasks:complete	Mark tasks complete (POST .../complete)
profile:read	Read user profile (GET /api/v1/user, GET /api/oauth/userinfo)

User

GET /api/v1/user

Scope: profile:read

{
  "id": "uuid",
  "email": "[email protected]",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "subscriptionTier": "FREE",
  "timezone": "America/New_York",
  "createdAt": "2025-01-01T00:00:00.000Z"
}

Tasks

GET /api/v1/tasks

Scope: tasks:read

Parameter	Description
completed	Optional. true or false to filter by completion.
limit	Optional. Max tasks (default 100, max 200).

Returns only the authenticated user's personal tasks (not group tasks). Recurring parents may show a computed next dueDate.

{
  "tasks": [
    {
      "id": "uuid",
      "classId": null,
      "title": "Read chapter 3",
      "description": null,
      "dueDate": "2026-03-28T00:00:00.000Z",
      "dueTime": null,
      "priority": "MEDIUM",
      "completed": false,
      "completedAt": null,
      "estimatedMinutes": 30,
      "isExam": false,
      "createdAt": "...",
      "updatedAt": "...",
      "class": null
    }
  ]
}

POST /api/v1/tasks

Scope: tasks:write

Field	Type	Required
title	string	Yes
description	string	No
dueDate	ISO date string	No
dueTime	string (HH:MM)	No
priority	LOW \| MEDIUM \| HIGH \| URGENT	No (default MEDIUM)
estimatedMinutes	number	No
isExam	boolean	No
classId	string \| null	No (must belong to the user)

Response (201):

{ "task": { ... } }

PATCH /api/v1/tasks/:id

Scope: tasks:write

Body (JSON): any subset of title, description, dueDate, dueTime, priority, completed, estimatedMinutes, isExam, classId.

{ "task": { ... } }

POST /api/v1/tasks/:id/complete

Scope: tasks:complete

Equivalent to patching the task with completed true (including recurring-task behavior where applicable).

{ "task": { ... } }

DELETE /api/v1/tasks/:id

Scope: tasks:write

{ "message": "Task deleted successfully" }

OAuth userinfo (OIDC-style profile)

GET /api/oauth/userinfo

Scope: profile:read (Bearer access token)

{
  "sub": "user-uuid",
  "email": "[email protected]",
  "given_name": "Ada",
  "family_name": "Lovelace",
  "subscription_tier": "FREE"
}

Errors

OAuth-style errors may include:

{ "error": "invalid_token", "error_description": "..." }

{ "error": "insufficient_scope", "error_description": "Required scope: tasks:read" }

Other routes may return { "error": "message" } with appropriate HTTP status codes (400, 401, 403, 404, 500).