> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Manage Todoist tasks and projects from Guild agents

> Connect Guild agents to Todoist to create, update, close, and delete tasks and projects, manage labels, comments, reminders, and workspaces.

Integrations · Todoist

Guild agents create, update, close, and delete Todoist tasks and projects on your team's behalf. Store the Todoist API key as a server-side credential so agent code never sees it, then use credential policies to restrict exactly which operations each agent can call.

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Todoist.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Todoist to your first agent.

## What the Todoist integration exposes

The integration is `guildai~todoist-openapi`. Tools cover tasks, projects, sections, labels, comments, reminders, folders, workspace membership, invitations, activity logs, productivity stats, backups, and template operations. Tools are prefixed `todoist_openapi_` and can be narrowed with `pick()` to include only what an agent needs. The catalog entry requires a Todoist API token, which Guild sends as a bearer token in the `Authorization` header.

## How it works

**1. Open credentials in Guild**

Go to **Access & setup > Credentials** in Guild and click **Connect**. Select **todoist-openapi** and paste your Todoist API key into the **API Key** field.

**2. Scope the credential**

Choose account, workspace, member, or agent scope. See [Credentials](https://docs.guild.ai/platform/credentials.md) for the difference between each scope and who can set them.

**3. Add tools to your agent**

Import `TodoistOpenapiTools` from `@guildai-services/guildai~todoist-openapi` and spread it into your agent's `tools` object. Use [`pick()`](https://docs.guild.ai/sdk/tools) to include only the tools your agent needs.

## Why Todoist access needs governing

Todoist tools can delete tasks and all their subtasks, delete projects and all their sections and tasks, remove workspace users, and revoke access tokens. An agent with unrestricted access to a shared credential can make changes that affect every member of a workspace. [Credential policies](https://docs.guild.ai/platform/credential-policies.md) let you write ALLOW and DENY rules that Guild's credential proxy enforces before any request reaches Todoist, limiting agents by operation name, HTTP method, workspace, or agent ID.

Credentials are injected server-side by Guild's proxy after the policy check passes. Agent code never sees the API key, and a matching DENY rule blocks a request even when an ALLOW rule also matches. [Credential scoping](https://docs.guild.ai/platform/credentials.md) lets you bind a credential to one agent, one workspace member, or one workspace, so a tightly scoped agent cannot reach data outside its remit.

## About the Todoist integration

Agents can create, update, close, and delete tasks and projects, organize work into sections and labels, and manage reminders and comments. They can also handle workspace membership, invitations, and folders. Productivity stats, activity logs, backups, and template operations are also available. The integration is `guildai~todoist-openapi`.

## Authentication

* **Type:** API key
* **Header:** Guild sends the key as a bearer token in the `Authorization` header

### Setup

**1. Connect Todoist**

In Guild, go to **Access & setup > Credentials**, click **Connect**, select **todoist-openapi**, and paste the key into **API Key**.

See [Credentials](https://docs.guild.ai/platform/credentials.md) for workspace, member, and agent-scoped credentials.

## Usage

```typescript theme={null}
import { TodoistOpenapiTools } from "@guildai-services/guildai~todoist-openapi"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  systemPrompt: "You work with Todoist.",
  tools: { ...TodoistOpenapiTools },
})
```

### Selecting specific tools

Tools are named with the `todoist_openapi_` prefix. Use [`pick()`](https://docs.guild.ai/sdk/tools#selecting-specific-tools) to include only what your agent needs.

## Tools

Tools in the latest published version of `guildai~todoist-openapi`:

> [accordion] All 123 tools
>
> | Tool | What it does |
> | - | - |
> | `todoist_openapi_accept_invitation_api_v1_workspaces_invitations_invite_code_accept_put` | Accept a workspace invitation. |
> | `todoist_openapi_active_projects_api_v1_workspaces_workspace_id_projects_active_get` | Returns all active workspace projects, including those visible but not joined by the user. |
> | `todoist_openapi_add_comment_reaction_api_v1_comments_comment_id_reactions_post` | Adds the authenticated user's reaction to a task or project comment and returns the updated comment. |
> | `todoist_openapi_all_invitations_api_v1_workspaces_invitations_all_get` | Return a list containing details of all pending invitation to a workspace. |
> | `todoist_openapi_archived_projects_api_v1_workspaces_workspace_id_projects_archived_get` | Return archived projects in a workspace. |
> | `todoist_openapi_archive_project_api_v1_projects_project_id_archive_post` | Marks a project as archived. |
> | `todoist_openapi_archive_section_api_v1_sections_section_id_archive_post` | Marks a section as archived. |
> | `todoist_openapi_cancel_plan_with_redirect_to_stripe_api_v1_payments_cancel_plan_with_redirect_to_stripe_post` | Start a hosted cancellation flow and return the redirect URL. |
> | `todoist_openapi_categories_api_v1_templates_categories_get` | List curated template categories. |
> | `todoist_openapi_close_task_api_v1_tasks_task_id_close_post` | Closes a task. |
> | `todoist_openapi_create_comment_api_v1_comments_post` | Creates a new comment on a project or task and returns it. |
> | `todoist_openapi_create_folder_api_v1_folders_post` | Create a new folder in the given workspace. |
> | `todoist_openapi_create_label_api_v1_labels_post` | Create a personal label. |
> | `todoist_openapi_create_location_reminder_api_v1_location_reminders_post` | Create a new location reminder for a task. |
> | `todoist_openapi_create_project_api_v1_projects_post` | Creates a new project and returns it |
> | `todoist_openapi_create_project_from_csv_api_v1_projects_import_post` | Create a project from CSV and return its ID and imported objects. |
> | `todoist_openapi_create_project_from_file_api_v1_templates_create_project_from_file_post` | A template can be imported in an existing project, or in a newly created one. |
> | `todoist_openapi_create_project_from_template_api_v1_projects_from_template_post` | Create a project from a template, returning only its ID and success status. |
> | `todoist_openapi_create_reminder_api_v1_reminders_post` | Create a new reminder for a task. |
> | `todoist_openapi_create_section_api_v1_sections_post` | Create a new section |
> | `todoist_openapi_create_task_api_v1_tasks_post` | Create a new task. |
> | `todoist_openapi_create_user_template_api_v1_templates_user_post` | Creates a template from a project or a content graph. |
> | `todoist_openapi_create_workspace_api_v1_workspaces_post` | Creates a new workspace and returns it. |
> | `todoist_openapi_delete_comment_api_v1_comments_comment_id_delete` | Delete a comment by ID |
> | `todoist_openapi_delete_filter_api_v1_filters_filter_id_delete` | Delete a personal filter. |
> | `todoist_openapi_delete_folder_api_v1_folders_folder_id_delete` | Delete a folder. |
> | `todoist_openapi_delete_invitation_api_v1_workspaces_invitations_delete_post` | Deletes a workspace invitation. |
> | `todoist_openapi_delete_label_api_v1_labels_label_id_delete` | Deletes a personal label. |
> | `todoist_openapi_delete_location_reminder_api_v1_location_reminders_reminder_id_delete` | Delete a location reminder by ID. |
> | `todoist_openapi_delete_project_api_v1_projects_project_id_delete` | Deletes a project and all of its sections and tasks. |
> | `todoist_openapi_delete_reminder_api_v1_reminders_reminder_id_delete` | Delete a reminder by ID. |
> | `todoist_openapi_delete_section_api_v1_sections_section_id_delete` | Delete the section and all of its tasks |
> | `todoist_openapi_delete_task_api_v1_tasks_task_id_delete` | Delete a task and all of its subtasks. |
> | `todoist_openapi_delete_upload_api_v1_uploads_delete` | Delete an uploaded file. |
> | `todoist_openapi_delete_workspace_api_v1_workspaces_workspace_id_delete` | Deletes a workspace. |
> | `todoist_openapi_discover_template_api_v1_templates_template_id_get` | Get one template. |
> | `todoist_openapi_discover_templates_api_v1_templates_get` | Discover templates or look up a bounded batch of IDs. |
> | `todoist_openapi_download_backup_api_v1_backups_download_get` | Download a backup archive. |
> | `todoist_openapi_email_disable_api_v1_emails_delete` | Disable the current email to a Todoist object |
> | `todoist_openapi_email_get_or_create_api_v1_emails_put` | Get or create an email to a Todoist object, currently only projects and tasks are supported. |
> | `todoist_openapi_export_as_url_api_v1_templates_url_get` | Publish a project as a shareable template URL. |
> | `todoist_openapi_generate_description_api_v1_templates_generate_description_post` | Generates an AI description from a project or saved template. |
> | `todoist_openapi_get_activity_logs_api_v1_activities_get` | Get activity logs. |
> | `todoist_openapi_get_archived_api_v1_projects_archived_get` | Get the user's archived projects. |
> | `todoist_openapi_get_backups_api_v1_backups_get` | Todoist creates a backup archive of users' data on a daily basis. |
> | `todoist_openapi_get_comment_api_v1_comments_comment_id_get` | Returns a single comment by ID |
> | `todoist_openapi_get_comments_api_v1_comments_get` | Get all comments for a given task or project. |
> | `todoist_openapi_get_folder_api_v1_folders_folder_id_get` | Return the folder for the given folder ID. |
> | `todoist_openapi_get_folders_api_v1_folders_get` | Get all folders for a workspace. |
> | `todoist_openapi_get_label_api_v1_labels_label_id_get` | Return a personal label by ID. |
> | `todoist_openapi_get_labels_api_v1_labels_get` | Get all user labels. |
> | `todoist_openapi_get_location_reminder_api_v1_location_reminders_reminder_id_get` | Return a single location reminder by ID. |
> | `todoist_openapi_get_location_reminders_api_v1_location_reminders_get` | Get all active location reminders. |
> | `todoist_openapi_get_productivity_stats_api_v1_tasks_completed_stats_get` | Get comprehensive productivity statistics for the authenticated user. |
> | `todoist_openapi_get_project_api_v1_projects_project_id_get` | Returns a project object related to the given ID |
> | `todoist_openapi_get_project_collaborators_api_v1_projects_project_id_collaborators_get` | Get all collaborators for a given project. |
> | `todoist_openapi_get_projects_api_v1_projects_get` | Get all active user projects, optionally filtered by folder or workspace. |
> | `todoist_openapi_get_reminder_api_v1_reminders_reminder_id_get` | Return a single reminder by ID. |
> | `todoist_openapi_get_reminders_api_v1_reminders_get` | Get all active reminders. |
> | `todoist_openapi_get_section_api_v1_sections_section_id_get` | Return the section for the given section ID |
> | `todoist_openapi_get_sections_api_v1_sections_get` | Get all active sections for the user, optionally filtered by project or workspace. |
> | `todoist_openapi_get_subscription_info_api_v1_payments_get_subscription_info_post` | Return the current user's subscription state. |
> | `todoist_openapi_get_task_api_v1_tasks_task_id_get` | Returns a single active (non-completed) task by ID |
> | `todoist_openapi_get_tasks_api_v1_tasks_get` | Get all active tasks for the user. |
> | `todoist_openapi_get_tasks_by_filter_api_v1_tasks_filter_get` | Get all tasks matching the filter. |
> | `todoist_openapi_get_workspace_api_v1_workspaces_workspace_id_get` | Returns a workspace by ID. |
> | `todoist_openapi_get_workspaces_api_v1_workspaces_get` | Returns all workspaces where the user is a member. |
> | `todoist_openapi_get_workspaces_users_api_v1_workspaces_users_get` | Returns all workspace\_users for a given workspace if workspace\_id is provided. |
> | `todoist_openapi_id_mappings_api_v1_id_mappings_obj_name_obj_ids_get` | Translates IDs from v1 to v2 or vice versa. |
> | `todoist_openapi_import_into_project_from_file_api_v1_templates_import_into_project_from_file_post` | A template can be imported in an existing project, or in a newly created one. |
> | `todoist_openapi_import_into_project_from_template_id_api_v1_templates_import_into_project_from_template_id_post` | Import a saved template into an existing project. |
> | `todoist_openapi_import_project_csv_api_v1_projects_project_id_import_post` | Import CSV into an existing project and return the imported objects. |
> | `todoist_openapi_import_project_template_api_v1_projects_project_id_import_template_post` | Import a project template, returning tasks, comments, reminders and applied defaults. |
> | `todoist_openapi_import_user_template_from_file_api_v1_templates_user_import_post` | Creates a personal template from CSV or a content graph. |
> | `todoist_openapi_invitations_api_v1_workspaces_invitations_get` | Return a list of user emails who have a pending invitation to a workspace. |
> | `todoist_openapi_invite_workspace_users_api_v1_workspaces_workspace_id_users_invite_post` | Invites users to a workspace by email. |
> | `todoist_openapi_join_api_v1_projects_project_id_join_post` | *Only used for workspaces* |
> | `todoist_openapi_join_api_v1_workspaces_join_post` | Join a workspace via link or via workspace ID, if the user can auto-join the workspace by domain. |
> | `todoist_openapi_migrate_personal_token_api_v1_access_tokens_migrate_personal_token_post` | Tokens obtained via the old email/password authentication method can be migrated to the new OAuth access token. |
> | `todoist_openapi_move_task_api_v1_tasks_task_id_move_post` | Moves task to another project, section or parent. |
> | `todoist_openapi_permissions_api_v1_projects_permissions_get` | Returns a list of all the available roles and the associated actions they can perform in a project. |
> | `todoist_openapi_plan_details_api_v1_workspaces_plan_details_get` | Lists details of the workspace's current plan and usage |
> | `todoist_openapi_preview_project_api_v1_templates_preview_get` | Preview a project's template graph. |
> | `todoist_openapi_preview_template_api_v1_templates_template_id_preview_get` | Preview a project or setup template without importing it. |
> | `todoist_openapi_preview_user_template_api_v1_templates_user_preview_post` | Stages and previews a project CSV sent as multipart `file` or a raw CSV body. |
> | `todoist_openapi_quick_add_api_v1_tasks_quick_post` | Add a new task using Quick Add with natural language processing. |
> | `todoist_openapi_reactivate_plan_api_v1_payments_reactivate_plan_post` | Reactivate a previously canceled subscription. |
> | `todoist_openapi_reject_invitation_api_v1_workspaces_invitations_invite_code_reject_put` | Reject a workspace invitation. |
> | `todoist_openapi_remove_comment_reaction_api_v1_comments_comment_id_reactions_remove_post` | Removes the authenticated user's reaction from a task or project comment. |
> | `todoist_openapi_remove_workspace_user_api_v1_workspaces_workspace_id_users_user_id_delete` | Removes a user from a workspace. |
> | `todoist_openapi_reopen_task_api_v1_tasks_task_id_reopen_post` | Reopens a task. |
> | `todoist_openapi_revoke_access_token_api_api_v1_access_tokens_delete` | Revoke the access tokens obtained via OAuth |
> | `todoist_openapi_revoke_token_rfc7009_compliant_api_v1_revoke_post` | Revoke an access token according to RFC 7009 OAuth Token Revocation. |
> | `todoist_openapi_search_labels_api_v1_labels_search_get` | Search user labels by name. |
> | `todoist_openapi_search_projects_api_v1_projects_search_get` | Search active user projects by name. |
> | `todoist_openapi_search_sections_api_v1_sections_search_get` | Search active sections by name, optionally filtered by project or workspace. |
> | `todoist_openapi_shared_labels_api_v1_labels_shared_get` | Returns a set of unique strings containing shared labels from active tasks. |
> | `todoist_openapi_shared_labels_remove_api_v1_labels_shared_remove_post` | Remove the given shared label from all active tasks |
> | `todoist_openapi_shared_labels_rename_api_v1_labels_shared_rename_post` | Rename the given shared label from all active tasks |
> | `todoist_openapi_tasks_completed_by_completion_date_api_v1_tasks_completed_by_completion_date_get` | Retrieves a list of completed tasks strictly limited by the specified completion date range (up to 3 months). |
> | `todoist_openapi_tasks_completed_by_due_date_api_v1_tasks_completed_by_due_date_get` | Retrieves a list of completed items strictly limited by the specified due date range (up to 6 weeks). |
> | `todoist_openapi_unarchive_project_api_v1_projects_project_id_unarchive_post` | Marks a previously archived project as active again. |
> | `todoist_openapi_unarchive_section_api_v1_sections_section_id_unarchive_post` | Marks a section as active again. |
> | `todoist_openapi_update_comment_api_v1_comments_comment_id_post` | Update a comment by ID and returns its content |
> | `todoist_openapi_update_folder_api_v1_folders_folder_id_post` | Update an existing folder. |
> | `todoist_openapi_update_label_api_v1_labels_label_id_post` | Update a personal label. |
> | `todoist_openapi_update_location_reminder_api_v1_location_reminders_reminder_id_post` | Update an existing location reminder. |
> | `todoist_openapi_update_logo_api_v1_workspaces_logo_post` | Upload an image to be used as the workspace logo. |
> | `todoist_openapi_update_notification_setting_api_v1_notification_setting_put` | Update a notification delivery preference. |
> | `todoist_openapi_update_project_api_v1_projects_project_id_post` | Updates a project and returns it. |
> | `todoist_openapi_update_reminder_api_v1_reminders_reminder_id_post` | Update an existing reminder. |
> | `todoist_openapi_update_section_api_v1_sections_section_id_post` | Update a section. |
> | `todoist_openapi_update_task_api_v1_tasks_task_id_post` | Updates an existing task. |
> | `todoist_openapi_update_user_template_api_v1_templates_user_template_id_put` | Updates a template's metadata and, optionally, its content. |
> | `todoist_openapi_update_workspace_api_v1_workspaces_workspace_id_post` | Updates an existing workspace and returns it. |
> | `todoist_openapi_update_workspace_user_api_v1_workspaces_workspace_id_users_user_id_post` | Updates a workspace user's role. |
> | `todoist_openapi_upload_file_api_v1_uploads_post` | Upload a file to Todoist. |
> | `todoist_openapi_usage_billing_history_api_v1_usage_billing_history_get` | List the caller's usage-billing ledger entries, newest first. |
> | `todoist_openapi_usage_billing_state_api_v1_usage_billing_state_get` | Read the caller's usage-billing credit state for a product. |
> | `todoist_openapi_usage_billing_top_up_api_v1_usage_billing_top_up_post` | In V1, create a hosted Stripe Checkout session to top up the authenticated user's personal Automations wallet. |
> | `todoist_openapi_usage_billing_usage_summary_api_v1_usage_billing_usage_summary_get` | Total the caller's settled usage over a window. |
> | `todoist_openapi_user_info_api_v1_user_get` | Get information about the currently authenticated user. |
> | `todoist_openapi_use_template_api_v1_templates_template_id_use_post` | Create a project or a complete setup from a template. |

## Frequently asked questions

> [accordion] Can an agent react to new Todoist tasks arriving in real time?
>
> No. The catalog entry for `guildai~todoist-openapi` lists no webhook events, so the integration does not support event-driven triggers from Todoist.

> [accordion] How do I stop an agent from deleting tasks or projects?
>
> Add a DENY rule in [credential policies](https://docs.guild.ai/platform/credential-policies.md) targeting operations such as `todoist_openapi_delete_task*` and `todoist_openapi_delete_project*`. A DENY rule takes precedence over any ALLOW rule and is enforced by Guild's credential proxy before the request reaches Todoist.

> [accordion] Does the agent ever see my Todoist API key?
>
> No. Guild stores the key as a server-side credential and injects it as a bearer token in the `Authorization` header after the credential policy check passes. The key never enters agent code, the agent's prompt, or its state.

> [accordion] Can one Todoist credential serve multiple workspaces?
>
> Yes. An account-scoped credential serves every workspace the account owns by default. You can also scope a credential to a single workspace, a single member, or a single agent. See [Credentials](https://docs.guild.ai/platform/credentials.md) for how Guild selects which credential to use when more than one is available.

## Put a governed agent on Todoist today

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Todoist.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Todoist to your first agent.

## Related

**Also runs on Guild:** [Asana](https://docs.guild.ai/integrations/asana.md) · [ClickUp](https://docs.guild.ai/integrations/clickup.md) · [Google Calendar](https://docs.guild.ai/integrations/google-calendar.md) · [Jira](https://docs.guild.ai/integrations/jira.md)

**Read:** Docs: [Credential policies](https://docs.guild.ai/platform/credential-policies.md) · [Credentials](https://docs.guild.ai/platform/credentials.md) · [Tools in agents](https://docs.guild.ai/sdk/tools.md)