To-do lists

July 23, 2026 · View on GitHub

Endpoints:

Get to-do lists

  • GET /todosets/3/todolists.json will return a paginated list of active to-do lists in the to-do set with ID of 3.

To get the to-do set ID for a project, see the Get to-do set endpoint.

Optional query parameters:

  • status - when set to archived or trashed, will return archived or trashed to-do lists that are in this to-do set.
Example JSON Response
[
  {
    "id": 1069480012,
    "status": "active",
    "visible_to_clients": false,
    "created_at": "2026-05-12T04:27:00.000Z",
    "updated_at": "2026-07-21T00:06:16.451Z",
    "title": "Strategy ideas",
    "inherits_status": true,
    "type": "Todolist",
    "url": "https://3.basecampapi.com/195539477/buckets/2085958505/todolists/1069480012.json",
    "app_url": "https://3.basecamp.com/195539477/buckets/2085958505/todolists/1069480012",
    "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7BkkiC19yYWlscwY6BkVUewdJIglkYXRhBjsAVEkiLmdpZDovL2JjMy9SZWNvcmRpbmcvMTA2OTQ4MDAxMj9leHBpcmVzX2luBjsAVEkiCHB1cgY7AFRJIg1yZWFkYWJsZQY7AFQ=--cfb66070fa4900acb4d47211d84e218c14831c7a.json",
    "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958505/recordings/1069480012/subscription.json",
    "comments_count": 0,
    "comments_url": "https://3.basecampapi.com/195539477/buckets/2085958505/recordings/1069480012/comments.json",
    "boosts_count": 0,
    "boosts_url": "https://3.basecampapi.com/195539477/buckets/2085958505/recordings/1069480012/boosts.json",
    "position": 3,
    "parent": {
      "id": 1069479829,
      "title": "To-dos",
      "type": "Todoset",
      "url": "https://3.basecampapi.com/195539477/buckets/2085958505/todosets/1069479829.json",
      "app_url": "https://3.basecamp.com/195539477/buckets/2085958505/todosets/1069479829"
    },
    "bucket": {
      "id": 2085958505,
      "name": "The Leto Laptop",
      "type": "Project"
    },
    "creator": {
      "id": 1049715913,
      "attachable_sgid": "BAh7BkkiC19yYWlscwY6BkVUewdJIglkYXRhBjsAVEkiK2dpZDovL2JjMy9QZXJzb24vMTA0OTcxNTkxMz9leHBpcmVzX2luBjsAVEkiCHB1cgY7AFRJIg9hdHRhY2hhYmxlBjsAVA==--e627c45e6b34e08862da23906862412620e4d5d9",
      "name": "Victor Cooper",
      "personable_type": "User",
      "title": "Chief Strategist",
      "tagline": "Don't let your dreams be dreams",
      "location": "Chicago, IL",
      "created_at": "2026-05-28T17:22:22.069Z",
      "updated_at": "2026-07-21T00:05:55.167Z",
      "email_address": "victor@honchodesign.com",
      "bio": "Don't let your dreams be dreams",
      "admin": true,
      "owner": true,
      "client": false,
      "employee": true,
      "time_zone": "America/Chicago",
      "avatar_url": "https://3.basecampapi.com/195539477/people/BAhpBMlkkT4=--5fe7b70fbee7a7f0e2e1e19df7579e5d880c753d/avatar",
      "company": {
        "id": 1033447817,
        "name": "Honcho Design"
      },
      "can_ping": true,
      "can_manage_projects": true,
      "can_manage_people": true,
      "can_access_timesheet": true,
      "can_access_hill_charts": true
    },
    "description": "",
    "description_attachments": [],
    "completed": false,
    "completed_ratio": "2/5",
    "name": "Strategy ideas",
    "color": null,
    "groups_url": "https://3.basecampapi.com/195539477/buckets/2085958505/todolists/1069480012/groups.json",
    "todos_url": "https://3.basecampapi.com/195539477/buckets/2085958505/todolists/1069480012/todos.json",
    "app_todos_url": "https://3.basecamp.com/195539477/buckets/2085958505/todolists/1069480012/todos",
    "comments_app_url": "https://3.basecamp.com/195539477/buckets/2085958505/recordings/1069480012/comments"
  }
]
Copy as cURL
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/todosets/3/todolists.json

Get a to-do list

  • GET /todolists/2.json will return the to-do list with an ID of 2.
Example JSON Response
{
  "id": 1069479863,
  "status": "active",
  "visible_to_clients": false,
  "created_at": "2026-04-16T23:22:00.000Z",
  "updated_at": "2026-07-21T01:05:29.822Z",
  "title": "Background and research",
  "inherits_status": true,
  "type": "Todolist",
  "url": "https://3.basecampapi.com/195539477/buckets/2085958505/todolists/1069479863.json",
  "app_url": "https://3.basecamp.com/195539477/buckets/2085958505/todolists/1069479863",
  "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7BkkiC19yYWlscwY6BkVUewdJIglkYXRhBjsAVEkiLmdpZDovL2JjMy9SZWNvcmRpbmcvMTA2OTQ3OTg2Mz9leHBpcmVzX2luBjsAVEkiCHB1cgY7AFRJIg1yZWFkYWJsZQY7AFQ=--d86bbb914defcac2db83950d3e617035efd1f679.json",
  "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958505/recordings/1069479863/subscription.json",
  "comments_count": 0,
  "comments_url": "https://3.basecampapi.com/195539477/buckets/2085958505/recordings/1069479863/comments.json",
  "boosts_count": 0,
  "boosts_url": "https://3.basecampapi.com/195539477/buckets/2085958505/recordings/1069479863/boosts.json",
  "position": 12,
  "parent": {
    "id": 1069479829,
    "title": "To-dos",
    "type": "Todoset",
    "url": "https://3.basecampapi.com/195539477/buckets/2085958505/todosets/1069479829.json",
    "app_url": "https://3.basecamp.com/195539477/buckets/2085958505/todosets/1069479829"
  },
  "bucket": {
    "id": 2085958505,
    "name": "The Leto Laptop",
    "type": "Project"
  },
  "creator": {
    "id": 1049715913,
    "attachable_sgid": "BAh7BkkiC19yYWlscwY6BkVUewdJIglkYXRhBjsAVEkiK2dpZDovL2JjMy9QZXJzb24vMTA0OTcxNTkxMz9leHBpcmVzX2luBjsAVEkiCHB1cgY7AFRJIg9hdHRhY2hhYmxlBjsAVA==--e627c45e6b34e08862da23906862412620e4d5d9",
    "name": "Victor Cooper",
    "personable_type": "User",
    "title": "Chief Strategist",
    "tagline": "Don't let your dreams be dreams",
    "location": "Chicago, IL",
    "created_at": "2026-05-28T17:22:22.069Z",
    "updated_at": "2026-07-21T00:05:55.167Z",
    "email_address": "victor@honchodesign.com",
    "bio": "Don't let your dreams be dreams",
    "admin": true,
    "owner": true,
    "client": false,
    "employee": true,
    "time_zone": "America/Chicago",
    "avatar_url": "https://3.basecampapi.com/195539477/people/BAhpBMlkkT4=--5fe7b70fbee7a7f0e2e1e19df7579e5d880c753d/avatar",
    "company": {
      "id": 1033447817,
      "name": "Honcho Design"
    },
    "can_ping": true,
    "can_manage_projects": true,
    "can_manage_people": true,
    "can_access_timesheet": true,
    "can_access_hill_charts": true
  },
  "description": "",
  "description_attachments": [],
  "completed": false,
  "completed_ratio": "1/5",
  "name": "Background and research",
  "color": "blue",
  "groups_url": "https://3.basecampapi.com/195539477/buckets/2085958505/todolists/1069479863/groups.json",
  "todos_url": "https://3.basecampapi.com/195539477/buckets/2085958505/todolists/1069479863/todos.json",
  "app_todos_url": "https://3.basecamp.com/195539477/buckets/2085958505/todolists/1069479863/todos",
  "comments_app_url": "https://3.basecamp.com/195539477/buckets/2085958505/recordings/1069479863/comments"
}
Copy as cURL
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/todolists/2.json

Create a to-do list

  • POST /todosets/3/todolists.json creates a to-do list under the to-do set with an ID of 3.

Required parameters: name of the to-do list.

Optional parameters:

  • description containing information about the to-do list. See our Rich text guide for what HTML tags are allowed.
  • visible_to_clients - top-level boolean. When the project has clients enabled, whether the to-do list is visible to them. Defaults to false (team callers creating directly under the docked tool); a client caller always creates client-visible records. See Client visibility to change it after creation.

This endpoint will return 201 Created with the current JSON representation of the to-do list if the creation was a success. See the Get a to-do list endpoint for more info on the payload.

Example JSON Request
{
  "name": "Launch",
  "description": "<div><em>Finish it!</em></div>"
}
Copy as cURL
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Launch","description":"<div><em>Finish it!</em></div>"}' \
  https://3.basecampapi.com/$ACCOUNT_ID/todosets/3/todolists.json

Update a to-do list

  • PUT /todolists/2.json allows changing the name and description of the to-do list with an ID of 2.

This endpoint will return 200 OK with the current JSON representation of the to-do list if the update was a success. See the Get a to-do list endpoint for more info on the payload.

Required parameters: Pass all existing parameters in addition to those being updated. Omitting a parameter will clear its value.

  • name of the to-do list. This one is always required, it can't be omitted as it can't be blank.

  • description containing information about the to-do list. See our Rich text guide for what HTML tags are allowed.

Example JSON Request
{
  "name": "Relaunch",
  "description": "<div><strong>Try this again.</strong></div>"
}
Copy as cURL
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Relaunch","description":"<div><strong>Try this again.</strong></div>"}' -X PUT \
  https://3.basecampapi.com/$ACCOUNT_ID/todolists/2.json

Reposition a to-do list

  • PUT /todosets/todolists/2/position.json repositions the to-do list with an ID of 2 within its to-do set.

Use this flat to-do list route for integrations. It applies the to-do list ordering rules for the list's to-do set.

This endpoint will return 204 No Content if the repositioning was a success.

Required parameters: position greater than or equal to one.

The position counts only the to-do set's incomplete to-do lists; completed lists are not counted. A position of 1 moves the list above all other incomplete lists.

Example JSON Request
{
  "position": 1
}
Copy as cURL
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"position":1}' -X PUT \
  https://3.basecampapi.com/$ACCOUNT_ID/todosets/todolists/2/position.json

Legacy project-scoped routes

The following project-scoped routes are still supported and will remain available, but flat routes above are the canonical form for new integrations.