From 616586281619e1c75b6b474f08d036f0b1414ca8 Mon Sep 17 00:00:00 2001 From: Rob Zolkos Date: Thu, 12 Mar 2026 16:04:04 -0400 Subject: [PATCH 1/3] Add my assignments API documentation (#9932) --- README.md | 1 + sections/my_assignments.md | 203 +++++++++++++++++++++++++++++++++++++ 2 files changed, 204 insertions(+) create mode 100644 sections/my_assignments.md diff --git a/README.md b/README.md index 5bc1cbb..aa88e98 100644 --- a/README.md +++ b/README.md @@ -305,6 +305,7 @@ API endpoints - [Message Boards](https://github.com/basecamp/bc3-api/blob/master/sections/message_boards.md#message-boards) - [Message Types](https://github.com/basecamp/bc3-api/blob/master/sections/message_types.md#message-types) - [Messages](https://github.com/basecamp/bc3-api/blob/master/sections/messages.md#messages) +- [My assignments](https://github.com/basecamp/bc3-api/blob/master/sections/my_assignments.md#my-assignments) - [People](https://github.com/basecamp/bc3-api/blob/master/sections/people.md#people) - [Projects](https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#projects) - [Question answers](https://github.com/basecamp/bc3-api/blob/master/sections/question_answers.md#question-answers) diff --git a/sections/my_assignments.md b/sections/my_assignments.md new file mode 100644 index 0000000..0a2570b --- /dev/null +++ b/sections/my_assignments.md @@ -0,0 +1,203 @@ +My assignments +=============== + +Endpoints for retrieving the current user's assignments, including active assignments split by priority, completed assignments, and due assignments filtered by time scope. + +Each assignment includes its content, type, bucket, parent, assignees, due dates, completion status, and any child assignments (e.g. card steps nested under their parent card). + +Endpoints: + +- [Get assignments](#get-assignments) +- [Get completed assignments](#get-completed-assignments) +- [Get due assignments](#get-due-assignments) + + +Get assignments +--------------- + +* `GET /my/assignments.json` will return the current user's active assignments grouped into `priorities` and `non_priorities`. Card table steps are normalized to their parent card, with steps included as `children`. + +###### Example JSON Response + +```json +{ + "priorities": [ + { + "id": 9007199254741623, + "app_url": "https://3.basecamp.com/195539477/buckets/2085958504/todos/9007199254741623", + "content": "Program the flux capacitor", + "starts_on": null, + "due_on": "2026-03-15", + "bucket": { + "id": 2085958504, + "name": "The Leto Laptop", + "app_url": "https://3.basecamp.com/195539477/buckets/2085958504" + }, + "completed": false, + "type": "todo", + "assignees": [ + { + "id": 1049715913, + "name": "Victor Cooper" + } + ], + "comments_count": 0, + "has_description": false, + "priority_recording_id": 9007199254741700, + "parent": { + "id": 9007199254741601, + "title": "Development tasks", + "app_url": "https://3.basecamp.com/195539477/buckets/2085958504/todolists/9007199254741601" + }, + "children": [] + } + ], + "non_priorities": [ + { + "id": 9007199254741650, + "app_url": "https://3.basecamp.com/195539477/buckets/2085958504/todos/9007199254741650", + "content": "Design the landing page", + "starts_on": null, + "due_on": null, + "bucket": { + "id": 2085958504, + "name": "The Leto Laptop", + "app_url": "https://3.basecamp.com/195539477/buckets/2085958504" + }, + "completed": false, + "type": "todo", + "assignees": [ + { + "id": 1049715913, + "name": "Victor Cooper" + } + ], + "comments_count": 2, + "has_description": true, + "parent": { + "id": 9007199254741601, + "title": "Development tasks", + "app_url": "https://3.basecamp.com/195539477/buckets/2085958504/todolists/9007199254741601" + }, + "children": [] + } + ] +} +``` + + +Assignments with card table steps are normalized so the parent card appears as the top-level item with its steps nested as `children`. Priority items include a `priority_recording_id` field. + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/my/assignments.json +``` + + +Get completed assignments +------------------------- + +* `GET /my/assignments/completed.json` will return the current user's completed assignments. Archived and trashed recordings are excluded. + +###### Example JSON Response + +```json +[ + { + "id": 9007199254741623, + "app_url": "https://3.basecamp.com/195539477/buckets/2085958504/todos/9007199254741623", + "content": "Program the flux capacitor", + "starts_on": null, + "due_on": "2026-03-15", + "bucket": { + "id": 2085958504, + "name": "The Leto Laptop", + "app_url": "https://3.basecamp.com/195539477/buckets/2085958504" + }, + "completed": true, + "type": "todo", + "assignees": [ + { + "id": 1049715913, + "name": "Victor Cooper" + } + ], + "comments_count": 0, + "has_description": false, + "parent": { + "id": 9007199254741601, + "title": "Development tasks", + "app_url": "https://3.basecamp.com/195539477/buckets/2085958504/todolists/9007199254741601" + }, + "children": [] + } +] +``` + + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/my/assignments/completed.json +``` + + +Get due assignments +------------------- + +* `GET /my/assignments/due.json` will return the current user's assignments filtered by due date scope. Defaults to `overdue` when no scope is provided. + +_Optional parameters_: + +* `scope` - filter by due date range. Valid options: `overdue`, `due_today`, `due_tomorrow`, `due_later_this_week`, `due_next_week`, `due_later`. + +Providing an invalid `scope` returns `400 Bad Request` with an error listing the valid options: + +```json +{ + "error": "Invalid scope 'invalid'. Valid options: overdue, due_today, due_tomorrow, due_later_this_week, due_next_week, due_later" +} +``` + +###### Example JSON Response + +```json +[ + { + "id": 9007199254741623, + "app_url": "https://3.basecamp.com/195539477/buckets/2085958504/todos/9007199254741623", + "content": "Program the flux capacitor", + "starts_on": null, + "due_on": "2026-03-10", + "bucket": { + "id": 2085958504, + "name": "The Leto Laptop", + "app_url": "https://3.basecamp.com/195539477/buckets/2085958504" + }, + "completed": false, + "type": "todo", + "assignees": [ + { + "id": 1049715913, + "name": "Victor Cooper" + } + ], + "comments_count": 0, + "has_description": false, + "parent": { + "id": 9007199254741601, + "title": "Development tasks", + "app_url": "https://3.basecamp.com/195539477/buckets/2085958504/todolists/9007199254741601" + }, + "children": [] + } +] +``` + + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/my/assignments/due.json?scope=overdue +``` From e3a5f2e83687b5498f4a541bcc1d8364323be1d0 Mon Sep 17 00:00:00 2001 From: Rob Zolkos Date: Thu, 12 Mar 2026 16:12:22 -0400 Subject: [PATCH 2/3] Note that assignment endpoints are not paginated --- sections/my_assignments.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/sections/my_assignments.md b/sections/my_assignments.md index 0a2570b..f984921 100644 --- a/sections/my_assignments.md +++ b/sections/my_assignments.md @@ -5,6 +5,8 @@ Endpoints for retrieving the current user's assignments, including active assign Each assignment includes its content, type, bucket, parent, assignees, due dates, completion status, and any child assignments (e.g. card steps nested under their parent card). +**Note:** These endpoints return the full result set and are not [paginated][pagination]. + Endpoints: - [Get assignments](#get-assignments) @@ -201,3 +203,5 @@ Providing an invalid `scope` returns `400 Bad Request` with an error listing the ```shell curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/my/assignments/due.json?scope=overdue ``` + +[pagination]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination From ad7be2b213e48c8f328672e9a5164540665c3c32 Mon Sep 17 00:00:00 2001 From: Rob Zolkos Date: Thu, 12 Mar 2026 16:13:28 -0400 Subject: [PATCH 3/3] Remove unnecessary pagination link --- sections/my_assignments.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/sections/my_assignments.md b/sections/my_assignments.md index f984921..8f7806e 100644 --- a/sections/my_assignments.md +++ b/sections/my_assignments.md @@ -5,7 +5,7 @@ Endpoints for retrieving the current user's assignments, including active assign Each assignment includes its content, type, bucket, parent, assignees, due dates, completion status, and any child assignments (e.g. card steps nested under their parent card). -**Note:** These endpoints return the full result set and are not [paginated][pagination]. +**Note:** These endpoints return the full result set and are not paginated. Endpoints: @@ -203,5 +203,3 @@ Providing an invalid `scope` returns `400 Bad Request` with an error listing the ```shell curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/my/assignments/due.json?scope=overdue ``` - -[pagination]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination