Todoist REST Port

Purpose

This is the Harbor reference integration for the Todoist REST API.

Use it when:

• building Todoist actions in Harbor
• extending the Dock / Hub Todoist entry
• teaching Codex or OpenClaw how to map a task-management REST API into Harbor Ports and Harbor Actions without turning Harbor into a generic Todoist query proxy

Harbor Port worksheet

Product

• Product: Todoist REST API
• Publisher slug: todoist
• Publisher name: Todoist
• Category: Work Management
• Tags: todoist, tasks, projects, productivity, planning

Safe Harbor Port metadata

• Kind: http_api
• Label: Todoist REST API
• Description: Todoist REST API connection managed locally through Harbor.
• Base URL: https://api.todoist.com/rest/v1/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

Todoist fits Harbor well because:

• every starter action stays on one fixed origin
• project and task endpoints are stable and explicit
• Harbor can model the safe filters as typed query inputs
• task creation maps cleanly to a bounded JSON request body
• Harbor never needs to expose raw auth or arbitrary sync/query transport

Good Harbor Todoist starter actions:

• fixed GET reads for projects and active tasks
• explicit POST writes for task creation
• requestBodyMode: "none" for reads
• requestBodyMode: "json" for writes
• resultMode: "json_summary" for all starter actions

Avoid for now:

• the broader Sync API surface
• freeform Todoist filter grammar as a first-wave Harbor action input
• large task mutation coverage before operator review
• generic forwarding across every Todoist endpoint

Starter Todoist actions

Automatic read actions

• list-projects -> GET /projects
• list-tasks -> GET /tasks

Approval-friendly write actions

• create-task -> POST /tasks

Why these actions

These routes fit Harbor's current safe model well because they:

• cover the common operator loop of discovering projects, reviewing active tasks, and creating a new task
• keep the route surface small and explicit
• use Harbor's Action Model for typed query values
• map cleanly to Todoist's bearer-token auth model
• give Harbor an immediately useful work-management integration without taking on Todoist's more flexible query and sync surfaces

Action Model notes

At execution time, callers should supply values by location:

• input.query for list-tasks
• input.body for create-task

Example task listing request:

{
  "query": {
    "project_id": 2203306141,
    "section_id": 7025
  }
}

Example task creation request:

{
  "body": {
    "content": "Review Harbor workflow draft",
    "description": "Check the Todoist port after import",
    "project_id": 2203306141,
    "priority": 4,
    "due_string": "tomorrow at 10:00"
  }
}

For create-task, keep the JSON body bounded to the fields you actually intend to use, such as:

• content
• description
• project_id
• section_id
• parent_id
• priority
• due_string
• due_lang

Suggested operator workflow

1. Import the Todoist Dock entry from Dock / Hub.
2. Configure the local Todoist bearer token in Harbor Node.
3. Use list-projects to discover project IDs first.
4. Use list-tasks with explicit project or section filters to inspect current work.
5. Keep create-task on require_approval unless there is a clear local policy reason not to.

Suggested agent workflow

1. Inspect the existing Todoist Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed Todoist routes only when they remain bounded and reviewable.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored Todoist token
• widen Todoist into a generic filter or sync proxy
• hide route names behind vague labels
• add broad mutation coverage without review

Current update strategy

For now, Todoist updates are manual:

• update the Dock / Hub Todoist integration document in apps/hub/catalog/integrations/todoist/todoist-rest-api.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Scope notes

This starter set is intentionally REST-only and avoids Todoist's broader freeform filtering and Sync API surface in the first pass.

That means:

• list-tasks currently exposes only explicit ID-based filters
• task creation is the only seeded write action
• additional task mutation or comment flows should be added later only when they remain fixed and reviewable

Official reference starting points

• Todoist REST API authorization: https://developer.todoist.com/rest/v1/
• Get all projects: https://developer.todoist.com/rest/v1/#get-all-projects
• Get active tasks: https://developer.todoist.com/rest/v1/#get-active-tasks
• Create a new task: https://developer.todoist.com/rest/v1/#create-a-new-task