├── CONDUCT.md ├── README.md └── sections ├── attachments.md ├── basecamps.md ├── campfires.md ├── card_table_cards.md ├── card_table_columns.md ├── card_table_steps.md ├── card_tables.md ├── chatbots.md ├── client_approvals.md ├── client_correspondences.md ├── client_replies.md ├── client_visibility.md ├── comments.md ├── documents.md ├── events.md ├── forwards.md ├── inbox_replies.md ├── inboxes.md ├── lineup_markers.md ├── message_boards.md ├── message_types.md ├── messages.md ├── people.md ├── projects.md ├── question_answers.md ├── questionnaires.md ├── questions.md ├── recordings.md ├── rich_text.md ├── schedule_entries.md ├── schedules.md ├── subscriptions.md ├── templates.md ├── todolist_groups.md ├── todolists.md ├── todos.md ├── todosets.md ├── uploads.md ├── vaults.md └── webhooks.md /CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to making participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, gender identity and expression, level of experience, 9 | nationality, personal appearance, race, religion, or sexual identity and 10 | orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or 41 | reject comments, commits, code, wiki edits, issues, and other contributions 42 | that are not aligned to this Code of Conduct, or to ban temporarily or 43 | permanently any contributor for other behaviors that they deem inappropriate, 44 | threatening, offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies both within project spaces and in public spaces 49 | when an individual is representing the project or its community. Examples of 50 | representing a project or community include using an official project e-mail 51 | address, posting via an official social media account, or acting as an appointed 52 | representative at an online or offline event. Representation of a project may be 53 | further defined and clarified by project maintainers. 54 | 55 | ## Enforcement 56 | 57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 58 | reported by contacting one of the project maintainers listed below. All 59 | complaints will be reviewed and investigated and will result in a response that 60 | is deemed necessary and appropriate to the circumstances. The project team is 61 | obligated to maintain confidentiality with regard to the reporter of an incident. 62 | Further details of specific enforcement policies may be posted separately. 63 | 64 | Project maintainers who do not follow or enforce the Code of Conduct in good 65 | faith may face temporary or permanent repercussions as determined by other 66 | members of the project's leadership. 67 | 68 | ## Project Maintainers 69 | 70 | * Javan Makhmali <> 71 | 72 | ## Attribution 73 | 74 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 75 | available at [http://contributor-covenant.org/version/1/4][version] 76 | 77 | [homepage]: http://contributor-covenant.org 78 | [version]: http://contributor-covenant.org/version/1/4/ 79 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | The Basecamp 4 API 2 | ================== 3 | 4 | Welcome to the Basecamp 4 API! If you're looking to integrate your application with Basecamp 4 or create your own application in concert with data inside of Basecamp 4, you're in the right place. We're happy to have you! 5 | 6 | 7 | Compatibility with previous Basecamp APIs 8 | ----------------------------------------- 9 | 10 | The Basecamp 4 API is not compatible with the [Basecamp Classic API](https://github.com/basecamp/basecamp-classic-api) or the [Basecamp 2 API](https://github.com/basecamp/bcx-api). All integrations will start fresh with the new API. The core ingredients are the same, though: Basecamp 4 is a REST-style API that uses JSON for serialization and OAuth 2.0 for authentication. 11 | 12 | 13 | What's different? 14 | ----------------- 15 | 16 | If you've used a previous version of the Basecamp API, you need to adapt your integration code. Here are some notable changes for the Basecamp 4 API: 17 | 18 | - We require OAuth 2.0 for [authentication](#authentication)—no more Basic authentication 19 | - [Pagination](#pagination) is performed via the `Link` and `X-Total-Count` headers 20 | 21 | 22 | Making a request 23 | ---------------- 24 | 25 | All URLs start with **`https://3.basecampapi.com/999999999/`**. URLs are HTTPS only. The path is prefixed with the account ID, but no `/api/v1` API prefix. Also, note the different domain! 26 | 27 | To make a request for all the projects on your account, append the `projects` index path to the base URL to form something like `https://3.basecampapi.com/999999999/projects.json`. In cURL, it looks like this: 28 | 29 | ``` shell 30 | curl -H "Authorization: Bearer $ACCESS_TOKEN" -A 'MyApp (yourname@example.com)' https://3.basecampapi.com/999999999/projects.json 31 | ``` 32 | 33 | To create something, it's the same idea, but you also have to include the `Content-Type` header and the JSON data: 34 | 35 | ``` shell 36 | curl -H "Authorization: Bearer $ACCESS_TOKEN" \ 37 | -H 'Content-Type: application/json' \ 38 | -A 'User-Agent: MyApp (yourname@example.com)' \ 39 | -d '{ "name": "My new project!" }' \ 40 | https://3.basecampapi.com/999999999/projects.json 41 | ``` 42 | 43 | Throughout the Basecamp 4 API docs, we include "Copy as cURL" examples. To try the examples in your shell, copy your OAuth 2.0 access token into your clipboard and run: 44 | 45 | ``` shell 46 | export ACCESS_TOKEN=PASTE_ACCESS_TOKEN_HERE 47 | export ACCOUNT_ID=999999999 48 | ``` 49 | 50 | Then you should be able to copy/paste any example from the docs. After pasting a cURL example, you can pipe it to a JSON pretty printer to make it more readable. Try [jsonpp](https://jmhodges.github.io/jsonpp/) or `json_pp` on OSX: 51 | 52 | ``` shell 53 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/999999999/projects.json | json_pp 54 | ``` 55 | 56 | Authentication 57 | -------------- 58 | 59 | As mentioned above, to authenticate you must use OAuth 2.0. OAuth 2.0 allows users to authorize your application to use Basecamp on their behalf without having to copy/paste API tokens or touch sensitive login information. 60 | 61 | Read the [authentication guide](https://github.com/basecamp/api/blob/master/sections/authentication.md) to get started. 62 | 63 | 64 | Identifying your application 65 | ---------------------------- 66 | 67 | You must include a `User-Agent` header with **both**: 68 | 69 | * The name of your application 70 | * A link to your application or your email address 71 | 72 | We use this information to get in touch if you're doing something wrong (so we can warn you before you're blacklisted) or something awesome (so we can congratulate you). Here are examples of acceptable `User-Agent` headers: 73 | 74 | * `User-Agent: Freshbooks (http://freshbooks.com/contact.php)` 75 | * `User-Agent: Fabian's Ingenious Integration (fabian@example.com)` 76 | 77 | If you don't include a `User-Agent` header, you'll get a `400 Bad Request` response. 78 | 79 | 80 | JSON only 81 | --------- 82 | 83 | We use JSON for all API data. The style is no root element and snake\_case for object keys. This means that you have to send the `Content-Type` header `Content-Type: application/json; charset=utf-8` when you're POSTing or PUTing data into Basecamp. All API URLs end in `.json` to indicate that they return JSON. Alternatively you can send `Accept: application/json`. 84 | 85 | You'll receive a `415 Unsupported Media Type` response code if you don't include the `Content-Type` header. 86 | 87 | 88 | Pagination 89 | ---------- 90 | 91 | Most collection APIs paginate their results. The number of requests that'll appear on each page is variable. In most cases, we use a [geared pagination ratio](https://github.com/basecamp/geared_pagination) with 15 results on page 1, 30 on page 2, 50 on 3, and then 100 on 4 and above. The Basecamp 4 API follows the [RFC5988 convention](https://tools.ietf.org/html/rfc5988) of using the `Link` header to provide URLs for the `next` page. Follow this convention to retrieve the next page of data—please don't build the pagination URLs yourself! 92 | 93 | Here's an example response header from requesting the third page of [messages](sections/messages.md#messages): 94 | 95 | ``` 96 | Link: ; rel="next" 97 | ``` 98 | 99 | If the `Link` header is blank, that's the last page. The Basecamp 4 API also provides the `X-Total-Count` header, which displays the total number of resources in the collection you are fetching. 100 | 101 | 102 | Using HTTP caching 103 | ------------------ 104 | 105 | You must use HTTP freshness headers to speed up your application and lighten the load on our servers. Most API responses will include an `ETag` or `Last-Modified` header. When you first request a resource, store these values. On subsequent requests, submit them back to us as `If-None-Match` and `If-Modified-Since`, respectively. If the resource hasn't changed since your last request, you'll get a `304 Not Modified` response with no body, saving you the time and bandwidth of sending something you already have. 106 | 107 | 108 | Handling errors 109 | --------------- 110 | 111 | API clients must expect and gracefully handle transient server errors and rate limits. We recommend baking graceful 5xx and 429 retries into your integration from the beginning so errors are handled automatically. 112 | 113 | ### Rate limiting (429 Too Many Requests) 114 | 115 | We return a [429 Too Many Requests](http://tools.ietf.org/html/draft-nottingham-http-new-status-02#section-4) response when you've exceeded a rate limit. Consult the `Retry-After` response header to determine how long to wait (in seconds) before retrying the request. 116 | 117 | Plan ahead to gracefully handle the failure modes that API backpressure will exert on your integration. Multiple rate limits are in effect, e.g. for GET vs POST requests and per-second/hour/day limits, and they're adjusted dynamically, so responding to them dynamically is essential, particularly at high traffic levels. 118 | 119 | For a sense of scale, the first rate limit you'll commonly encounter is currently 50 requests per 10 second period per IP address. 120 | 121 | ### [5xx server errors](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#5xx_Server_errors) 122 | 123 | If Basecamp is having trouble, you will get a response with a 5xx status code indicating a server error. 500 (Internal Server Error), 502 (Bad Gateway), 503 (Service Unavailable), and 504 (Gateway Timeout) may be retried with [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff). 124 | 125 | ### 404 Not Found 126 | 127 | API requests may 404 due to deleted content, an inactive account, missing user permissions, etc. Detect these conditions to give your users a clear explanation about why they can't connect to Basecamp. Do not automatically retry these requests. 128 | 129 | * Inactive account. 404 Not Found response with a `Reason: Account Inactive` header. Due to an expired trial or account suspension. All API requests to an inactive account will fail, so we recommend detecting and disabling the account in your integration as well. 130 | * Inaccessible items. 404 Not Found response. Due to a deleted item or insufficient permissions. 131 | 132 | 133 | Rich text content 134 | ----------------- 135 | 136 | Many resources, including messages, documents, and comments, represent their content as rich text in HTML. Rich text content may contain lists, block quotes, simple formatting, and inline attachments such as mentions, images, and files. 137 | 138 | See the [Rich text](sections/rich_text.md) section for more information about working with HTML and attachments in rich text content. 139 | 140 | 141 | API endpoints 142 | ------------- 143 | 144 | - [Attachments](https://github.com/basecamp/bc3-api/blob/master/sections/attachments.md#attachments) 145 | - [Campfires](https://github.com/basecamp/bc3-api/blob/master/sections/campfires.md#campfires) 146 | - [Card table cards](https://github.com/basecamp/bc3-api/blob/master/sections/card_table_cards.md#card-table-cards) 147 | - [Card table columns](https://github.com/basecamp/bc3-api/blob/master/sections/card_table_columns.md#card-table-columns) 148 | - [Card table steps](https://github.com/basecamp/bc3-api/blob/master/sections/card_table_steps.md#card-table-steps) 149 | - [Card tables](https://github.com/basecamp/bc3-api/blob/master/sections/card_tables.md#card-tables) 150 | - [Chatbots](https://github.com/basecamp/bc3-api/blob/master/sections/chatbots.md#chatbots) 151 | - [Client approvals](https://github.com/basecamp/bc3-api/blob/master/sections/client_approvals.md#client-approvals) 152 | - [Client correspondences](https://github.com/basecamp/bc3-api/blob/master/sections/client_correspondences.md#client-correspondences) 153 | - [Client replies](https://github.com/basecamp/bc3-api/blob/master/sections/client_replies.md#client-replies) 154 | - [Client visibility](https://github.com/basecamp/bc3-api/blob/master/sections/client_visibility.md#client-visibility) 155 | - [Comments](https://github.com/basecamp/bc3-api/blob/master/sections/comments.md#comments) 156 | - [Documents](https://github.com/basecamp/bc3-api/blob/master/sections/documents.md#documents) 157 | - [Events](https://github.com/basecamp/bc3-api/blob/master/sections/events.md#events) 158 | - [Forwards](https://github.com/basecamp/bc3-api/blob/master/sections/forwards.md#forwards) 159 | - [Inbox replies](https://github.com/basecamp/bc3-api/blob/master/sections/inbox_replies.md#inbox-replies) 160 | - [Inboxes](https://github.com/basecamp/bc3-api/blob/master/sections/inboxes.md#inboxes) 161 | - [Lineup Markers](https://github.com/basecamp/bc3-api/blob/master/sections/lineup_markers.md#lineup-markers) 162 | - [Message Boards](https://github.com/basecamp/bc3-api/blob/master/sections/message_boards.md#message-boards) 163 | - [Message Types](https://github.com/basecamp/bc3-api/blob/master/sections/message_types.md#message-types) 164 | - [Messages](https://github.com/basecamp/bc3-api/blob/master/sections/messages.md#messages) 165 | - [People](https://github.com/basecamp/bc3-api/blob/master/sections/people.md#people) 166 | - [Projects](https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#projects) 167 | - [Question answers](https://github.com/basecamp/bc3-api/blob/master/sections/question_answers.md#question-answers) 168 | - [Questionnaires](https://github.com/basecamp/bc3-api/blob/master/sections/questionnaires.md#questionnaires) 169 | - [Questions](https://github.com/basecamp/bc3-api/blob/master/sections/questions.md#questions) 170 | - [Recordings](https://github.com/basecamp/bc3-api/blob/master/sections/recordings.md#recordings) 171 | - [Schedule entries](https://github.com/basecamp/bc3-api/blob/master/sections/schedule_entries.md#schedule-entries) 172 | - [Schedules](https://github.com/basecamp/bc3-api/blob/master/sections/schedules.md#schedules) 173 | - [Subscriptions](https://github.com/basecamp/bc3-api/blob/master/sections/subscriptions.md#subscriptions) 174 | - [Templates](https://github.com/basecamp/bc3-api/blob/master/sections/templates.md#templates) 175 | - [To-do list groups](https://github.com/basecamp/bc3-api/blob/master/sections/todolist_groups.md#to-do-list-groups) 176 | - [To-do lists](https://github.com/basecamp/bc3-api/blob/master/sections/todolists.md#to-do-lists) 177 | - [To-do sets](https://github.com/basecamp/bc3-api/blob/master/sections/todosets.md#to-do-sets) 178 | - [To-dos](https://github.com/basecamp/bc3-api/blob/master/sections/todos.md#to-dos) 179 | - [Uploads](https://github.com/basecamp/bc3-api/blob/master/sections/uploads.md#uploads) 180 | - [Vaults](https://github.com/basecamp/bc3-api/blob/master/sections/vaults.md#vaults) 181 | - [Webhooks](https://github.com/basecamp/bc3-api/blob/master/sections/webhooks.md#webhooks) 182 | 183 | 184 | 185 | Listing your application 186 | ------------------------ 187 | 188 | To add your application to our public list of Basecamp 4 integrations, go to [https://github.com/basecamp/bc3-integrations](https://github.com/basecamp/bc3-integrations) and open a pull request. 189 | 190 | Getting Help 191 | ------------ 192 | 193 | If you have a question about the API, please [open a support ticket](https://basecamp.com/support). 194 | 195 | 196 | Conduct 197 | ------- 198 | 199 | Please note that this project is released with a [Contributor Code of Conduct](https://github.com/basecamp/bc3-api/blob/master/CONDUCT.md). By participating in discussions about the Basecamp 4 API, you agree to abide by these terms. 200 | 201 | 202 | License 203 | ------- 204 | 205 | These API docs are licensed under [Creative Commons (CC BY-SA 4.0)](http://creativecommons.org/licenses/by-sa/4.0/). Please share, remix, and distribute as you see fit. 206 | -------------------------------------------------------------------------------- /sections/attachments.md: -------------------------------------------------------------------------------- 1 | Attachments 2 | =========== 3 | 4 | Endpoints: 5 | 6 | - [Create an attachment](#create-an-attachment) 7 | 8 | 9 | Create an attachment 10 | -------------------- 11 | 12 | * `POST /attachments.json` uploads a file. 13 | 14 | **Required request data**: The request body should be the file's raw binary data. 15 | 16 | **Required request headers**: `Content-Type` and `Content-Length` for to the file. 17 | 18 | **Required URI query parameters**: `name` as the file name. 19 | 20 | This endpoint will return `201 Created` with the attachment's `attachable_sgid` in the JSON representation. 21 | 22 | ###### Example JSON Response 23 | 24 | ```json 25 | { 26 | "attachable_sgid": "BAh2CEkiCGdpZAY6BkVUSSIsZ2lkOi7vYmMzL0F0dGFjaG1lbnQvNzM4NDcyNj9leHBpcmVzX2luBjsAVEkiDHB1cnBvc2UGOwBUSSIPYXR0YWNoYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--13982201abe18044c897e32979c7dccfe8add9c1" 27 | } 28 | ``` 29 | 30 | ###### Copy as cURL 31 | 32 | ``` shell 33 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ 34 | --data-binary @pizza.png \ 35 | -H "Content-Type: image/png" -H "Content-Length: 123" \ 36 | https://3.basecampapi.com/$ACCOUNT_ID/attachments.json?name=pizza.png 37 | ``` 38 | 39 | Including attachments in rich text in other recordings 40 | ------------------------------------------------------ 41 | 42 | Check [Inserting an image or file attachment](https://github.com/basecamp/bc3-api/blob/master/sections/rich_text.md#inserting-an-image-or-file-attachment) for details on how to do this. 43 | -------------------------------------------------------------------------------- /sections/basecamps.md: -------------------------------------------------------------------------------- 1 | Basecamps 2 | ========= 3 | 4 | Projects used to be called _Basecamps_, but not anymore. See the [Projects](https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#projects) section for documentation. 5 | -------------------------------------------------------------------------------- /sections/campfires.md: -------------------------------------------------------------------------------- 1 | Campfires 2 | ========= 3 | 4 | Endpoints: 5 | 6 | - [Get Campfires](#get-campfires) 7 | - [Get a Campfire](#get-a-campfire) 8 | - [Get Campfire lines](#get-campfire-lines) 9 | - [Get a Campfire line](#get-a-campfire-line) 10 | - [Create a Campfire line](#create-a-campfire-line) 11 | - [Delete a Campfire line](#delete-a-campfire-line) 12 | 13 | Get Campfires 14 | ------------- 15 | 16 | * `GET /chats.json` will return a [paginated list][pagination] of all active Campfires visible to the current user. 17 | 18 | ###### Example JSON Response 19 | 20 | ```json 21 | [ 22 | { 23 | "id": 1069478933, 24 | "status": "active", 25 | "visible_to_clients": false, 26 | "created_at": "2022-08-25T10:04:24.930Z", 27 | "updated_at": "2022-11-22T08:23:30.837Z", 28 | "title": "Campfire", 29 | "inherits_status": true, 30 | "type": "Chat::Transcript", 31 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/chats/1069478933.json", 32 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/chats/1069478933", 33 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc4OTMzP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--f3045584f2792d1d77b9cf8dcaff57d9b0177e0b.json", 34 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958497/recordings/1069478933/subscription.json", 35 | "position": 4, 36 | "bucket": { 37 | "id": 2085958497, 38 | "name": "Honcho Design Newsroom", 39 | "type": "Project" 40 | }, 41 | "creator": { 42 | "id": 1049715914, 43 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 44 | "name": "Victor Cooper", 45 | "email_address": "victor@honchodesign.com", 46 | "personable_type": "User", 47 | "title": "Chief Strategist", 48 | "bio": "Don’t let your dreams be dreams", 49 | "location": "Chicago, IL", 50 | "created_at": "2022-11-22T08:23:21.732Z", 51 | "updated_at": "2022-11-22T08:23:21.904Z", 52 | "admin": true, 53 | "owner": true, 54 | "client": false, 55 | "employee": true, 56 | "time_zone": "America/Chicago", 57 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 58 | "company": { 59 | "id": 1033447817, 60 | "name": "Honcho Design" 61 | }, 62 | "can_manage_projects": true, 63 | "can_manage_people": true 64 | }, 65 | "topic": "Campfire", 66 | "lines_url": "https://3.basecampapi.com/195539477/buckets/2085958497/chats/1069478933/lines.json" 67 | } 68 | ] 69 | ``` 70 | 71 | ###### Copy as cURL 72 | 73 | ``` shell 74 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/chats.json 75 | ``` 76 | 77 | Get a Campfire 78 | -------------- 79 | 80 | * `GET /buckets/1/chats/2.json` will return the Campfire with ID `2` in the project with ID `1`. 81 | 82 | ###### Example JSON Response 83 | 84 | ```json 85 | { 86 | "id": 1069478933, 87 | "status": "active", 88 | "visible_to_clients": false, 89 | "created_at": "2022-08-25T10:04:24.930Z", 90 | "updated_at": "2022-11-22T08:23:30.837Z", 91 | "title": "Campfire", 92 | "inherits_status": true, 93 | "type": "Chat::Transcript", 94 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/chats/1069478933.json", 95 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/chats/1069478933", 96 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc4OTMzP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--f3045584f2792d1d77b9cf8dcaff57d9b0177e0b.json", 97 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958497/recordings/1069478933/subscription.json", 98 | "position": 4, 99 | "bucket": { 100 | "id": 2085958497, 101 | "name": "Honcho Design Newsroom", 102 | "type": "Project" 103 | }, 104 | "creator": { 105 | "id": 1049715914, 106 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 107 | "name": "Victor Cooper", 108 | "email_address": "victor@honchodesign.com", 109 | "personable_type": "User", 110 | "title": "Chief Strategist", 111 | "bio": "Don’t let your dreams be dreams", 112 | "location": "Chicago, IL", 113 | "created_at": "2022-11-22T08:23:21.732Z", 114 | "updated_at": "2022-11-22T08:23:21.904Z", 115 | "admin": true, 116 | "owner": true, 117 | "client": false, 118 | "employee": true, 119 | "time_zone": "America/Chicago", 120 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 121 | "company": { 122 | "id": 1033447817, 123 | "name": "Honcho Design" 124 | }, 125 | "can_manage_projects": true, 126 | "can_manage_people": true 127 | }, 128 | "topic": "Campfire", 129 | "lines_url": "https://3.basecampapi.com/195539477/buckets/2085958497/chats/1069478933/lines.json" 130 | } 131 | ``` 132 | 133 | ###### Copy as cURL 134 | 135 | ``` shell 136 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/chats/2.json 137 | ``` 138 | 139 | Get Campfire lines 140 | ------------------ 141 | 142 | * `GET /buckets/1/chats/2/lines.json` will return a [paginated list][pagination] of Campfire lines of the Campfire with ID `2` in the project with ID `1`. 143 | 144 | ###### Example JSON Response 145 | 146 | ```json 147 | [ 148 | { 149 | "id": 1069479015, 150 | "status": "active", 151 | "visible_to_clients": false, 152 | "created_at": "2022-08-25T08:23:24.930Z", 153 | "updated_at": "2022-08-25T08:23:24.930Z", 154 | "title": "I'm hungry", 155 | "inherits_status": true, 156 | "type": "Chat::Lines::Text", 157 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/chats/1069478933/lines/1069479015.json", 158 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/chats/1069478933@1069479015", 159 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5MDE1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--9d750749b82162ec684b4cf4747080694b766b8f.json", 160 | "parent": { 161 | "id": 1069478933, 162 | "title": "Campfire", 163 | "type": "Chat::Transcript", 164 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/chats/1069478933.json", 165 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/chats/1069478933" 166 | }, 167 | "bucket": { 168 | "id": 2085958497, 169 | "name": "Honcho Design Newsroom", 170 | "type": "Project" 171 | }, 172 | "creator": { 173 | "id": 1049715936, 174 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTM2P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--49bf4c17af8bc53bf5ecc54cfe98e24cc45aeaa0", 175 | "name": "Matt Donahue", 176 | "email_address": "matt@honchodesign.com", 177 | "personable_type": "User", 178 | "title": "Global Data Strategist", 179 | "bio": null, 180 | "location": null, 181 | "created_at": "2022-11-22T08:23:22.205Z", 182 | "updated_at": "2022-11-22T08:23:22.205Z", 183 | "admin": false, 184 | "owner": false, 185 | "client": false, 186 | "employee": false, 187 | "time_zone": "Etc/UTC", 188 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBOBkkT4=--78fb2ba7c3091268f41638ef90dee7dd32f395d6/avatar?v=1", 189 | "can_manage_projects": true, 190 | "can_manage_people": true 191 | }, 192 | "content": "I'm hungry" 193 | } 194 | ] 195 | ``` 196 | 197 | ###### Copy as cURL 198 | 199 | ``` shell 200 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/chats/2/lines.json 201 | ``` 202 | 203 | Get a Campfire line 204 | ------------------- 205 | 206 | * `GET /buckets/1/chats/2/lines/3.json` will return the Campfire line with ID `3` in the Campfire with ID `2` in the project with ID `1`. 207 | 208 | ###### Example JSON Response 209 | 210 | ```json 211 | { 212 | "id": 1069479001, 213 | "status": "active", 214 | "visible_to_clients": false, 215 | "created_at": "2022-08-25T08:23:24.930Z", 216 | "updated_at": "2022-08-25T08:23:24.930Z", 217 | "title": "👏 🎉", 218 | "inherits_status": true, 219 | "type": "Chat::Lines::Text", 220 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/chats/1069478933/lines/1069479001.json", 221 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/chats/1069478933@1069479001", 222 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5MDAxP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--c8a4576fc2f2c0fbf4a4015fc4f34128f4c20d42.json", 223 | "parent": { 224 | "id": 1069478933, 225 | "title": "Campfire", 226 | "type": "Chat::Transcript", 227 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/chats/1069478933.json", 228 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/chats/1069478933" 229 | }, 230 | "bucket": { 231 | "id": 2085958497, 232 | "name": "Honcho Design Newsroom", 233 | "type": "Project" 234 | }, 235 | "creator": { 236 | "id": 1049715922, 237 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTIyP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--90ea53b2b0ce32a96bcc6ef712c1fac0dbb0a0cd", 238 | "name": "Amy Rivera", 239 | "email_address": "amy@honchodesign.com", 240 | "personable_type": "User", 241 | "title": "Central Web Coordinator", 242 | "bio": "I never said most of the things I said", 243 | "location": null, 244 | "created_at": "2022-11-22T08:23:22.005Z", 245 | "updated_at": "2022-11-22T08:23:22.005Z", 246 | "admin": false, 247 | "owner": false, 248 | "client": false, 249 | "employee": false, 250 | "time_zone": "Etc/UTC", 251 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBNJkkT4=--6ef93d58440c2ed1fec4457e3eb5f09572e866a4/avatar?v=1", 252 | "can_manage_projects": true, 253 | "can_manage_people": true 254 | }, 255 | "content": "👏 🎉" 256 | } 257 | ``` 258 | 259 | ###### Copy as cURL 260 | 261 | ``` shell 262 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/chats/2/lines/3.json 263 | ``` 264 | 265 | Create a Campfire line 266 | ---------------------- 267 | 268 | * `POST /buckets/1/chats/2/lines.json` creates a line in the Campfire with ID `2` in the project with ID `1`. 269 | 270 | **Required parameters**: `content` as the plain text body for the Campfire line. 271 | 272 | This endpoint will return `201 Created` with the current JSON representation of the line if the creation was a success. See the [Get a Campfire line](#get-a-campfire-line) endpoint for more info on the payload. 273 | 274 | ###### Example JSON Request 275 | 276 | ``` json 277 | { 278 | "content": "Good morning" 279 | } 280 | ``` 281 | 282 | ###### Copy as cURL 283 | 284 | ``` shell 285 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 286 | -d '{"content":"Good morning"}' \ 287 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/chats/2/lines.json 288 | ``` 289 | 290 | Delete a Campfire line 291 | ---------------------- 292 | 293 | * `DELETE /buckets/1/chats/2/lines/3.json` will delete the Campfire line with ID `3` in the Campfire with ID `2` in the project with ID `1`. 294 | 295 | Returns `204 No Content` if successful. 296 | 297 | ###### Copy as cURL 298 | 299 | ``` shell 300 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/chats/2/lines/3.json 301 | ``` 302 | 303 | [pagination]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination 304 | -------------------------------------------------------------------------------- /sections/card_table_columns.md: -------------------------------------------------------------------------------- 1 | Card table columns 2 | ================ 3 | 4 | Endpoints: 5 | 6 | - [Get a column](#get-a-column) 7 | - [Create a column](#create-a-column) 8 | - [Update a column](#update-a-column) 9 | - [Move a column](#move-a-column) 10 | - [Watch a column](#watch-a-column) 11 | - [Change on hold on a column](#change-on-hold-on-a-column) 12 | - [Change color of a column](#change-color-of-a-column) 13 | 14 | Get a column 15 | ------------- 16 | 17 | * `GET /buckets/1/card_tables/columns/2.json` will return the column with an ID of `2` in the project with an ID of `1`. 18 | 19 | ###### Example JSON Response 20 | 21 | ```json 22 | { 23 | "id": 1069482092, 24 | "status": "active", 25 | "visible_to_clients": false, 26 | "created_at": "2022-11-18T09:51:27.242Z", 27 | "updated_at": "2022-11-18T09:51:41.806Z", 28 | "title": "Triage", 29 | "inherits_status": true, 30 | "type": "Kanban::Triage", 31 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/card_tables/columns/1069482092.json", 32 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/card_tables/columns/1069482092", 33 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDgyMDkyP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--4e5003c6ebe9d448a770f00a1b3da52b6f668c65.json", 34 | "parent": { 35 | "id": 1069482091, 36 | "title": "Card Table", 37 | "type": "Kanban::Board", 38 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/card_tables/1069482091.json", 39 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/card_tables/1069482091" 40 | }, 41 | "bucket": { 42 | "id": 2085958499, 43 | "name": "The Leto Laptop", 44 | "type": "Project" 45 | }, 46 | "creator": { 47 | "id": 1049716070, 48 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE2MDcwP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--5cfb1d97d8544362aa74062bc84b66fbf1d7a853", 49 | "name": "Victor Cooper", 50 | "email_address": "victor@honchodesign.com", 51 | "personable_type": "User", 52 | "title": "Chief Strategist", 53 | "bio": "Don’t let your dreams be dreams", 54 | "location": "Chicago, IL", 55 | "created_at": "2022-11-18T09:50:54.566Z", 56 | "updated_at": "2022-11-18T09:50:54.760Z", 57 | "admin": true, 58 | "owner": true, 59 | "client": false, 60 | "employee": true, 61 | "time_zone": "America/Chicago", 62 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBGZlkT4=--b295b0b432557d4a03760f78668284d4f39bf563/avatar?v=1", 63 | "company": { 64 | "id": 1033447825, 65 | "name": "Honcho Design" 66 | }, 67 | "can_manage_projects": true, 68 | "can_manage_people": true 69 | }, 70 | "description": null, 71 | "subscribers": [ 72 | 73 | ], 74 | "color": null, 75 | "cards_count": 1, 76 | "comment_count": 0, 77 | "cards_url": "https://3.basecampapi.com/195539477/buckets/2085958499/card_tables/lists/1069482092/cards.json" 78 | } 79 | ``` 80 | 81 | ###### Copy as cURL 82 | 83 | ``` shell 84 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/card_tables/columns/2.json 85 | ``` 86 | 87 | Create a column 88 | ------------------------- 89 | 90 | * `POST /buckets/1/card_tables/2/columns.json` creates a column within the card table with ID `2` in the project with id `1`. 91 | 92 | **Required parameters**: `title` of the column. 93 | 94 | _Optional parameters_: 95 | 96 | * `description` - containing information about the column. 97 | 98 | This endpoint will return `201 Created` with the current JSON representation of the column if the creation was a success. See the [Get a column](#get-a-column) endpoint for more info on the payload. 99 | 100 | ###### Example JSON Request 101 | 102 | ``` json 103 | { 104 | "title": "In progress", 105 | "description": "Stuff we are working on actively" 106 | } 107 | ``` 108 | 109 | ###### Copy as cURL 110 | 111 | ``` shell 112 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 113 | -d '{"title":"In progress"}' \ 114 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/card_tables/2/columns.json 115 | ``` 116 | 117 | Update a column 118 | ----------------------- 119 | 120 | * `PUT /buckets/1/card_tables/columns/2.json` allows changing of the column with an ID of `2` in the project with ID `1`. 121 | 122 | This endpoint will return `200 OK` with the current JSON representation of the column if the update was a success. See the [Get a column](#get-a-column) endpoint for more info on the payload. 123 | 124 | ###### Example JSON Request 125 | 126 | ``` json 127 | { 128 | "title": "On it", 129 | "description": "Stuff we are doing right now" 130 | } 131 | ``` 132 | 133 | ###### Copy as cURL 134 | 135 | ``` shell 136 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 137 | -d '{"title":"On it", "description":"Stuff we are doing right now"}' -X PUT \ 138 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/card_tables/columns/2.json 139 | ``` 140 | 141 | Move a column 142 | ----------------------- 143 | 144 | * `POST /buckets/1/card_tables/2/moves.json` allows moving of a column in the card table with id `2` in the project with ID `1`. 145 | 146 | **Required parameters**: 147 | 148 | * `source_id` - the id of the column to move 149 | * `target_id` - the id of the card table 150 | 151 | _Optional parameters_: 152 | 153 | * `position` - index among the columns (ignoring Triage, Not Now or Done). Default: `1` 154 | 155 | This endpoint will return `204 No content` if the update was a success. 156 | 157 | ###### Example JSON Request 158 | 159 | ``` json 160 | { 161 | "source_id": 3, 162 | "targed_id": 4, 163 | "position": 2 164 | } 165 | ``` 166 | ###### Copy as cURL 167 | 168 | ``` shell 169 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 170 | -d '{"source_id": 3, "target_id":4, "position": 2}' \ 171 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/card_tables/2/moves.json 172 | ``` 173 | 174 | Watch a column 175 | ----------------------- 176 | * `POST /buckets/1/card_tables/lists/2/subscription.json` starts watching the column with id `2` in the project with ID `1`. 177 | * `DELETE /buckets/1/card_tables/lists/2/subscription.json` stops watching the column with id `2` in the project with ID `1`. 178 | 179 | This endpoint will return `204 No content` if the update was a success. 180 | 181 | ###### Copy as cURL 182 | ``` shell 183 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 184 | -X POST \ 185 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/card_tables/lists/2/subscription.json 186 | ``` 187 | ``` shell 188 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 189 | -X DELETE \ 190 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/card_tables/lists/2/subscription.json 191 | ``` 192 | 193 | Change on hold on a column 194 | ----------------------- 195 | 196 | * `POST /buckets/1/card_tables/columns/2/on_hold.json` creates an on_hold section in the column with ID `2` in the project with id `1`. 197 | * `DELETE /buckets/1/card_tables/columns/2/on_hold.json` removes an on_hold section in the column with ID `2` in the project with id `1`. 198 | 199 | This endpoint will return `200 Success` with the current JSON representation of the column if the operation was a success. See the [Get a column](#get-a-column) endpoint for more info on the payload. 200 | 201 | ###### Copy as cURL 202 | 203 | ``` shell 204 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 205 | -X POST \ 206 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/card_tables/columns/2/on_hold.json 207 | ``` 208 | ``` shell 209 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 210 | -X DELETE \ 211 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/card_tables/columns/2/on_hold.json 212 | ``` 213 | 214 | Change color of a column 215 | ----------------------- 216 | 217 | * `PUT /buckets/1/card_tables/columns/2/color.json` allows changing the color of the column with an ID of `2` in the project with ID `1`. 218 | 219 | This endpoint will return `200 OK` with the current JSON representation of the column if the update was a success. See the [Get a column](#get-a-column) endpoint for more info on the payload. 220 | 221 | 222 | **Required parameters**: 223 | 224 | * `color` - the color. Available values: `[ white red orange yellow green blue aqua purple gray pink brown ]` 225 | 226 | ###### Example JSON Request 227 | 228 | ``` json 229 | { 230 | "color": "orange" 231 | } 232 | ``` 233 | 234 | ###### Copy as cURL 235 | 236 | ``` shell 237 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 238 | -d '{"color":"orange"}' -X PUT \ 239 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/card_tables/columns/2/color.json 240 | ``` 241 | 242 | -------------------------------------------------------------------------------- /sections/card_table_steps.md: -------------------------------------------------------------------------------- 1 | Card table steps 2 | ================ 3 | 4 | Endpoints: 5 | 6 | - [Get steps in a card](#get-steps-in-a-card) 7 | - [Create a step](#create-a-step) 8 | - [Update a step](#update-a-step) 9 | - [Change step completion status](#change-step-completion-status) 10 | - [Reposition a step](#reposition-a-step) 11 | 12 | Get steps in a card 13 | -------------------- 14 | 15 | Steps are returned unpaginated as part of the [Get a card][card] endpoint payload. 16 | 17 | Create a step 18 | ------------------------- 19 | 20 | * `POST /buckets/1/card_tables/cards/2/steps.json` creates a step within the card with ID `2` in the project with id `1`. 21 | 22 | **Required parameters**: `title` of the step. 23 | 24 | _Optional parameters_: 25 | 26 | * `due_on` - due date (ISO 8601) of the step. 27 | * `assignees` - a comma separated list of people ids that will be assigned to this step. Please see the [Get people][people] endpoints to retrieve them. 28 | 29 | This endpoint will return `201 Created` with the current JSON representation of the step if the creation was a success. See the step property of the [Get a card][card] endpoint for more info on the payload. 30 | 31 | ###### Example JSON Request 32 | 33 | ``` json 34 | { 35 | "title": "Inspiration", 36 | "due_on": "2021-01-01", 37 | "assignees": "30068628,270913789" 38 | } 39 | ``` 40 | 41 | ###### Copy as cURL 42 | 43 | ``` shell 44 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 45 | -d '{"title": "Inspiration", "due_on": "2021-01-01", "assignees": "30068628,270913789"}' \ 46 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/card_tables/cards/2/steps.json 47 | ``` 48 | 49 | Update a step 50 | ----------------------- 51 | 52 | * `PUT /buckets/1/card_tables/steps/2.json` allows changing of the step with an ID of `2` in the project with ID `1`. 53 | 54 | _Optional parameters_: 55 | 56 | * `title` - of the card. 57 | * `due_on` - due date (ISO 8601) of the step. 58 | * `assignees` - a comma separated list of people ids that will be assigned to this step. Please see the [Get people][people] endpoints to retrieve them. 59 | 60 | This endpoint will return `200 OK` with the current JSON representation of the step if the update was a success. See the step property of the [Get a card][card] endpoint for more info on the payload. 61 | 62 | ###### Example JSON Request 63 | 64 | ``` json 65 | { 66 | "title": "Updated inspiration" 67 | } 68 | ``` 69 | 70 | ###### Copy as cURL 71 | 72 | ``` shell 73 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 74 | -d '{"title": "Updated inspiration"}' -X PUT \ 75 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/card_tables/steps/2.json 76 | ``` 77 | 78 | Change step completion status 79 | ----------------------------- 80 | 81 | * `PUT /buckets/1/card_tables/steps/2/completions.json` will mark the step with an ID of `2` in the project with ID `1` as completed or uncompleted depending on the completion parameter. 82 | 83 | **Required parameters**: 84 | 85 | * `completion` – Set to "on" to mark the step as completed and to "off" to mark the step as uncompleted. 86 | 87 | This endpoint will return `200 OK` with the current JSON representation of the step if the update was a success. See the step property of the [Get a card][card] endpoint for more info on the payload. 88 | 89 | ###### Example JSON Request 90 | 91 | ``` json 92 | { 93 | "completion": "on" 94 | } 95 | ``` 96 | 97 | ###### Copy as cURL 98 | 99 | ``` shell 100 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 101 | -d '{"completion": "on"}' -X PUT \ 102 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/card_tables/steps/2/completions.json 103 | ``` 104 | 105 | Reposition a step 106 | ----------------------------- 107 | 108 | * `POST /buckets/1/card_tables/cards/2/positions.json` allows changing the position of the step with an ID of `source_id` in the card with id `2`. 109 | 110 | **Required parameters**: 111 | 112 | * `source_id` – the step id. Step ids can be found via the [Get a card][card] endpoint. 113 | * `position` – Zero indexed. 114 | 115 | This endpoint will return `204 No Content` if successful. 116 | 117 | ###### Example JSON Request 118 | 119 | ``` json 120 | { 121 | "source_id": 3, 122 | "position": 4 123 | } 124 | ``` 125 | 126 | ``` shell 127 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 128 | -d '{"source_id": 3, "position": 4}' -X POST \ 129 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/card_tables/cards/2/positions.json 130 | ``` 131 | 132 | [card]: https://github.com/basecamp/bc3-api/blob/master/sections/card_table_cards.md#get-a-card 133 | [people]: https://github.com/basecamp/bc3-api/blob/master/sections/people.md#get-all-people 134 | -------------------------------------------------------------------------------- /sections/chatbots.md: -------------------------------------------------------------------------------- 1 | Chatbots 2 | ======== 3 | 4 | There are two types of chatbots in Basecamp: Those that are interactive and those that only post content on their own. 5 | Interactive chatbots can be queried or commanded by anyone in any room. You can even start a ping conversation with one. 6 | 7 | Both types of chatbots are authenticated differently from how the rest of the API works. There's no OAuth exchange to perform. 8 | Interactive chatbots have their queries and commands POST'ed directly to them with a piece of JSON. Whatever they return to 9 | that POST is inserted into the room where the conversation is happening. 10 | 11 | Alternatively, if a chatbot needs to post on their own, there's a special key'ed URL that's all that is needed. It's returned 12 | as `lines_url` when creating a chatbot. See the [Create a chatbot](#create-a-chatbot) endpoint for more info. If you have that 13 | URL, you can post content as that chatbot to that room. But what you can't do is read anything from the room. This is not a 14 | streaming service. It's intended purely for request/reply and blind reply interactions. 15 | 16 | When an interactive chatbot is invoked, it'll receive a JSON payload like this: 17 | 18 | ```json 19 | { 20 | "command": "What up?", 21 | "creator": { 22 | "id": 1007299143, 23 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbQQcMDA3Mjk5MTQzP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--919d2c8b11ff403eefcab9db42dd26846d0c3102", 24 | "name": "Victor Cooper", 25 | "email_address": "victor@honchodesign.com", 26 | "personable_type": "User", 27 | "title": "Chief Strategist", 28 | "bio": "Don't let your dreams be dreams", 29 | "created_at": "2016-09-22T16:21:03.625-05:00", 30 | "updated_at": "2016-09-22T16:21:06.184-05:00", 31 | "admin": true, 32 | "owner": true, 33 | "time_zone": "America/Chicago", 34 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBEcqCjw=--c632b967cec296b87363a697a67a87f9cc1e5b45/avatar-64-x4", 35 | "company": { 36 | "id": 1033447817, 37 | "name": "Honcho Design" 38 | } 39 | }, 40 | "callback_url": "https://3.basecamp.com/195539477/integrations/2uH9aHLEVhhaXKPaqrj8yw8P/buckets/2085958501/chats/9007199254741775/lines" 41 | } 42 | ``` 43 | 44 | You can use the information in the creator block to enforce permission controls. If you have a deploy bot, then maybe only certain 45 | people, with pre-specified IDs, will be able to interact with it. 46 | 47 | If the interactive chatbot is able to provide a response right away, it can, as stated above, just return that as part 48 | of a text/html content-typed response with status code 200. This response has the same format as all other rich text in Basecamp, 49 | but also accepts these additional tags: `table tr td th thead tbody details summary`. The pair of details/summary is particularly 50 | useful for providing large chunks of information hidden behind a show/hide. 51 | 52 | Here are a few examples of return content or content sent to the callback URL from what we use at Basecamp: 53 | 54 | Alert warning from Nagios with inline resolution links: 55 | 56 | ```html 57 |
🔴 CRITICAL some.ip.37signals.com Http Profile /Common/bc3_anycast_production_https_profile
CRIT - High Error Levels - 20 4xx, 0 5xx
58 |

Unacknowledged

59 |

60 | Acknowledge | 61 | Disable Notifications | 62 | Schedule 2hr Downtime 63 |

64 |

Status changed less than a minute ago and was previously Warning.

65 |
66 | ``` 67 | 68 | Status update from AWS: 69 | 70 | ```html 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 |
ServiceMessageDate/Time
DIRECTCONNECTInformational message: Network ConnectivityFri, 16 Sep 2016 12:11:03 -0700
INTERNETCONNECTIVITYService is operating normally: [RESOLVED] Network ConnectivityTue, 20 Sep 2016 05:31:00 -0700
INTERNETCONNECTIVITYInformational message: Network ConnectivityFri, 23 Sep 2016 08:47:13 -0700
INTERNETCONNECTIVITYService is operating normally: [RESOLVED] Network ConnectivityWed, 14 Sep 2016 01:31:00 -0700
SQSService is operating normally: [RESOLVED] Increased API Error RatesTue, 20 Sep 2016 12:44:00 -0700
105 | ``` 106 | 107 | It's important to note that chatbots are account-wide, but with basecamp-specific callback URLs. So you create a chatbot on a specific 108 | Basecamp to get the callback URL for that Basecamp, but the chatbot will instantly be available to every other Basecamp on the account as well. 109 | This also means that any edits or deletes of chatbots are account-wide. For this reason, chatbots can only be managed by administrators. 110 | But everyone is able to interact with interactive chatbots and all you need to post as a chatbot is that callback URL. 111 | 112 | Endpoints: 113 | 114 | - [Get chatbots](#get-chatbots) 115 | - [Get a chatbot](#get-a-chatbot) 116 | - [Create a chatbot](#create-a-chatbot) 117 | - [Update a chatbot](#update-a-chatbot) 118 | - [Destroy a chatbot](#destroy-a-chatbot) 119 | - [Create a line](#create-a-line) 120 | 121 | Get chatbots 122 | ------------ 123 | 124 | * `GET /buckets/1/chats/1/integrations.json` will return all the chatbots from the account with the line URL for the campfire on the basecamp with an ID of `1`. 125 | 126 | ###### Example JSON Response 127 | 128 | ```json 129 | [ 130 | { 131 | "id": 1049715958, 132 | "created_at": "2022-11-22T08:25:04.466Z", 133 | "updated_at": "2022-11-22T08:25:04.466Z", 134 | "service_name": "Capistrano", 135 | "command_url": null, 136 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/chats/1069478933/integrations/1049715958.json", 137 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/chats/1069478933/integrations/1049715958", 138 | "lines_url": "https://3.basecampapi.com/195539477/integrations/B5JQYvHsNWCoDvYGZfH1xNR9/buckets/2085958497/chats/1069478933/lines" 139 | } 140 | ] 141 | ``` 142 | 143 | 144 | ###### Copy as cURL 145 | 146 | ``` shell 147 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/chats/1/integrations.json 148 | ``` 149 | 150 | Get a chatbot 151 | ------------- 152 | 153 | * `GET /buckets/1/chats/1/integrations/3.json` will return the chatbot with an ID of `3` with the line URL from the project with ID `1`. 154 | 155 | ###### Example JSON Response 156 | 157 | ```json 158 | [ 159 | { 160 | "id": 1007299181, 161 | "created_at": "2016-09-23T00:04:47.833Z", 162 | "updated_at": "2016-09-23T00:04:47.833Z", 163 | "service_name": "dash", 164 | "command_url": "https://example.com/command", 165 | "url": "https://3.basecampapi.com/195539477/buckets/2085958496/chats/9007199254741045/integrations/1007299181.json", 166 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958496/chats/9007199254741045/integrations/1007299181", 167 | "lines_url": "https://3.basecampapi.com/195539477/integrations/yFU7K9oKrcZyvYLDw4GfLU89/buckets/2085958496/chats/9007199254741045/lines" 168 | } 169 | ] 170 | ``` 171 | 172 | ###### Copy as cURL 173 | 174 | ``` shell 175 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/chats/1/integrations/3.json 176 | ``` 177 | 178 | Create a chatbot 179 | ---------------- 180 | 181 | * `POST /buckets/1/chats/1/integrations.json` creates a chatbot on the account and returns the new chatbot with the lines URL from the project with ID `1`. 182 | 183 | **Required parameters**: `service_name` for the chatbot name, which will be used to invoke queries and commands on interactive bots. 184 | No spaces, emoji or non-word characters are allowed, as you need to be able to call it like `!tally myCommand` 185 | _Optional parameters_: `command_url` for the HTTPS url that Basecamp should call when the bot is addressed. 186 | 187 | This endpoint will return `201 Created` with the current JSON representation of the chatbot if the creation was a success. See the [Get a chatbot](#get-a-chatbot) endpoint for more info on the payload. 188 | 189 | ###### Example JSON Request 190 | 191 | ``` json 192 | { 193 | "service_name": "tally", 194 | "command_url": "https://example.com/endpoint" 195 | } 196 | ``` 197 | 198 | ###### Copy as cURL 199 | 200 | ``` shell 201 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 202 | -d '{"service_name":"tally","command_url":"https://example.com/endpoint"}' \ 203 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/chats/1/integrations.json 204 | ``` 205 | 206 | Update a chatbot 207 | ---------------- 208 | 209 | * `PUT /buckets/1/chats/1/integrations/3.json` allows changing the service name and commandURL of the chatbot with an ID of `3` in the project with ID `1`. 210 | 211 | **Required parameters**: `service_name` for the chatbot name, which will be used to invoke queries and commands on interactive bots. 212 | No spaces, emoji or non-word characters are allowed, as you need to be able to call it like `!tally myCommand` 213 | _Optional parameters_: `command_url` for the HTTPS url that Basecamp should call when the bot is addressed. 214 | 215 | This endpoint will return `200 OK` with the current JSON representation of the chatbot if the update was a success. See the [Get a chatbot](#get-a-chatbot) endpoint for more info on the payload. 216 | 217 | ###### Example JSON Request 218 | 219 | ``` json 220 | { 221 | "service_name": "uptime", 222 | "command_url": "https://example.com/endpoint" 223 | } 224 | ``` 225 | 226 | ###### Copy as cURL 227 | 228 | ``` shell 229 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 230 | -d '{"service_name":"uptime","command_url":"https://example.com/endpoint"}' -X PUT \ 231 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/chats/1/integrations/3.json 232 | ``` 233 | 234 | Destroy a chatbot 235 | ----------------- 236 | 237 | * `DELETE /buckets/1/chats/1/integrations/3.json` will delete the chatbot with an ID of `3` across the account. 238 | 239 | This endpoint will return `204 No Content` if the destroy was a success. 240 | 241 | ###### Copy as cURL 242 | 243 | ``` shell 244 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE \ 245 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/chatbots/3.json 246 | ``` 247 | 248 | Create a line 249 | ------------- 250 | 251 | * `POST /integrations/$CHATBOT_KEY/buckets/1/chats/2/lines.json` creates a line in the Campfire with ID `2` in the project with ID `1`. 252 | 253 | **Required parameters**: `content` as the body for the Campfire line. See our [Rich text guide][1] for what HTML tags are allowed. 254 | 255 | _Optional parameters_: 256 | 257 | * `content_param` - modifies the name of the required `content` param to support webhooks from a third-party, e.g. Slack with a `text` param 258 | 259 | In addition to the tags permitted for all rich text, the following tags are permitted for chatbot lines: `table`, `tr`, `td`, `th`, `thead`, `tbody`, `details`, and `summary`. 260 | 261 | This endpoint will return `201 Created` if the creation was a success. 262 | 263 | ###### Example JSON Request 264 | 265 | ``` json 266 | { 267 | "content": "Good morning" 268 | } 269 | ``` 270 | 271 | ###### Copy as cURL 272 | 273 | ``` shell 274 | curl -s -H "Content-Type: application/json" -d '{"content":"Good morning"}' \ 275 | https://3.basecampapi.com/$ACCOUNT_ID/integrations/$CHATBOT_KEY/buckets/1/chats/2/lines.json 276 | ``` 277 | 278 | or, with a custom content_param called `text`: 279 | 280 | ``` shell 281 | curl -s -H "Content-Type: application/json" -d '{"text":"Good morning"}' \ 282 | https://3.basecampapi.com/$ACCOUNT_ID/integrations/$CHATBOT_KEY/buckets/1/chats/2/lines.json?content_param=text 283 | ``` 284 | 285 | [1]: https://github.com/basecamp/bc3-api/blob/master/sections/rich_text.md 286 | -------------------------------------------------------------------------------- /sections/client_approvals.md: -------------------------------------------------------------------------------- 1 | Client approvals 2 | ================ 3 | 4 | Endpoints: 5 | 6 | - [Get client approvals](#get-client-approvals) 7 | - [Get a client approval](#get-a-client-approval) 8 | 9 | Get client approvals 10 | -------------------- 11 | 12 | * `GET /buckets/1/client/approvals.json` will return a [paginated list][pagination] of client approvals in the project with an ID of `1`. 13 | 14 | ###### Example JSON Response 15 | 16 | ```json 17 | [ 18 | { 19 | "id": 1069479654, 20 | "status": "active", 21 | "visible_to_clients": false, 22 | "created_at": "2022-11-21T12:13:14.049Z", 23 | "updated_at": "2022-11-22T08:24:21.287Z", 24 | "title": "Business card", 25 | "inherits_status": true, 26 | "type": "Client::Approval", 27 | "url": "https://3.basecampapi.com/195539477/buckets/2085958500/client/approvals/1069479654.json", 28 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958500/client/approvals/1069479654", 29 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5NjU0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--9cfe8a2356c54d6c68971d684758701488bccd00.json", 30 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958500/recordings/1069479654/subscription.json", 31 | "parent": { 32 | "id": 1069479564, 33 | "title": "The Clientside", 34 | "type": "Client::Board", 35 | "url": "https://3.basecampapi.com/195539477/buckets/2085958500/client/board.json", 36 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958500/client/board.1069479564" 37 | }, 38 | "bucket": { 39 | "id": 2085958500, 40 | "name": "The Leto Locator", 41 | "type": "Project" 42 | }, 43 | "creator": { 44 | "id": 1049715915, 45 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--aeb392ebf54ffd820e45f27add22bae3a8c7da56", 46 | "name": "Annie Bryan", 47 | "email_address": "annie@honchodesign.com", 48 | "personable_type": "User", 49 | "title": "Central Markets Manager", 50 | "bio": "To open a store is easy, to keep it open is an art", 51 | "location": null, 52 | "created_at": "2022-11-22T08:23:21.911Z", 53 | "updated_at": "2022-11-22T08:23:21.911Z", 54 | "admin": false, 55 | "owner": false, 56 | "client": false, 57 | "employee": true, 58 | "time_zone": "America/Chicago", 59 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMtkkT4=--9927c47a4cbee30a7f9aea667882496aba799149/avatar?v=1", 60 | "company": { 61 | "id": 1033447817, 62 | "name": "Honcho Design" 63 | }, 64 | "can_manage_projects": true, 65 | "can_manage_people": true 66 | }, 67 | "content": "
OK, here's another one! We've got this business card worked up, just need your yes or no to proceed. Thanks!

\n
\n
\n images-images-bcard-2.jpg\n
\n
", 68 | "subject": "Business card", 69 | "due_on": null, 70 | "replies_count": 0, 71 | "replies_url": "https://3.basecampapi.com/195539477/buckets/2085958500/client/recordings/1069479654/replies.json", 72 | "approval_status": "pending", 73 | "approver": { 74 | "id": 1049715942, 75 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTQyP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--fa05bcc15bdd53f8a944ba3f2386b0ec8aedfc73", 76 | "name": "Miranda Grant", 77 | "email_address": "miranda@letobrand.com", 78 | "personable_type": "Client", 79 | "title": "Dynamic Markets Analyst", 80 | "bio": null, 81 | "location": null, 82 | "created_at": "2022-11-22T08:23:22.343Z", 83 | "updated_at": "2022-11-22T08:23:22.343Z", 84 | "admin": false, 85 | "owner": false, 86 | "client": false, 87 | "employee": false, 88 | "time_zone": "Etc/UTC", 89 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBOZkkT4=--b8553b154990a1112ab6275b749296c4a3b56334/avatar?v=1", 90 | "company": { 91 | "id": 1033447818, 92 | "name": "Leto Brand" 93 | }, 94 | "can_manage_projects": false, 95 | "can_manage_people": false 96 | } 97 | } 98 | ] 99 | ``` 100 | 101 | ###### Copy as cURL 102 | 103 | ``` shell 104 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/client/approvals.json 105 | ``` 106 | 107 | Get a client approval 108 | --------------------- 109 | 110 | * `GET /buckets/1/client/approvals/2.json` will return the client approval with an ID of `2` in the project with an ID of `1`. 111 | 112 | ###### Example JSON Response 113 | 114 | ```json 115 | { 116 | "id": 1069479651, 117 | "status": "active", 118 | "visible_to_clients": false, 119 | "created_at": "2022-11-18T09:54:14.049Z", 120 | "updated_at": "2022-11-22T08:24:21.164Z", 121 | "title": "New logo for the website", 122 | "inherits_status": true, 123 | "type": "Client::Approval", 124 | "url": "https://3.basecampapi.com/195539477/buckets/2085958500/client/approvals/1069479651.json", 125 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958500/client/approvals/1069479651", 126 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5NjUxP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--e141c7eaa049920cdc4bb43d509f3c99ae537f68.json", 127 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958500/recordings/1069479651/subscription.json", 128 | "parent": { 129 | "id": 1069479564, 130 | "title": "The Clientside", 131 | "type": "Client::Board", 132 | "url": "https://3.basecampapi.com/195539477/buckets/2085958500/client/board.json", 133 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958500/client/board.1069479564" 134 | }, 135 | "bucket": { 136 | "id": 2085958500, 137 | "name": "The Leto Locator", 138 | "type": "Project" 139 | }, 140 | "creator": { 141 | "id": 1049715915, 142 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--aeb392ebf54ffd820e45f27add22bae3a8c7da56", 143 | "name": "Annie Bryan", 144 | "email_address": "annie@honchodesign.com", 145 | "personable_type": "User", 146 | "title": "Central Markets Manager", 147 | "bio": "To open a store is easy, to keep it open is an art", 148 | "location": null, 149 | "created_at": "2022-11-22T08:23:21.911Z", 150 | "updated_at": "2022-11-22T08:23:21.911Z", 151 | "admin": false, 152 | "owner": false, 153 | "client": false, 154 | "employee": true, 155 | "time_zone": "America/Chicago", 156 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMtkkT4=--9927c47a4cbee30a7f9aea667882496aba799149/avatar?v=1", 157 | "company": { 158 | "id": 1033447817, 159 | "name": "Honcho Design" 160 | }, 161 | "can_manage_projects": true, 162 | "can_manage_people": true 163 | }, 164 | "content": "
Hey! We've wrapped up work on the new logo for the website and wanted to get your final sign off. What do you think? Let us know when you get a chance!

\n
\n
\n images-coudal-logo.jpg\n
\n
", 165 | "subject": "New logo for the website", 166 | "due_on": null, 167 | "replies_count": 0, 168 | "replies_url": "https://3.basecampapi.com/195539477/buckets/2085958500/client/recordings/1069479651/replies.json", 169 | "approval_status": "approved", 170 | "approver": { 171 | "id": 1049715941, 172 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTQxP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--10099ab54fac5884db30b9bd897ea030023d4d0a", 173 | "name": "Stephen Early", 174 | "email_address": "stephen@letobrand.com", 175 | "personable_type": "Client", 176 | "title": "National Directives Director", 177 | "bio": null, 178 | "location": null, 179 | "created_at": "2022-11-22T08:23:22.341Z", 180 | "updated_at": "2022-11-22T08:23:22.341Z", 181 | "admin": false, 182 | "owner": false, 183 | "client": false, 184 | "employee": false, 185 | "time_zone": "Etc/UTC", 186 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBOVkkT4=--33e3fc268c87411378691c71b6f13658e0b40967/avatar?v=1", 187 | "company": { 188 | "id": 1033447818, 189 | "name": "Leto Brand" 190 | }, 191 | "can_manage_projects": false, 192 | "can_manage_people": false 193 | }, 194 | "responses": [ 195 | { 196 | "id": 1069479653, 197 | "status": "active", 198 | "visible_to_clients": false, 199 | "created_at": "2022-11-18T10:47:14.049Z", 200 | "updated_at": "2022-11-18T10:47:14.049Z", 201 | "title": "Answer Re: New logo for the website", 202 | "inherits_status": true, 203 | "type": "Client::Approval::Response", 204 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958500/client/approvals/1069479651#__recording_1069479653", 205 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5NjUzP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--df835cb45337b87233145ffb48304200c319c153.json", 206 | "parent": { 207 | "id": 1069479651, 208 | "title": "New logo for the website", 209 | "type": "Client::Approval", 210 | "url": "https://3.basecampapi.com/195539477/buckets/2085958500/client/approvals/1069479651.json", 211 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958500/client/approvals/1069479651" 212 | }, 213 | "bucket": { 214 | "id": 2085958500, 215 | "name": "The Leto Locator", 216 | "type": "Project" 217 | }, 218 | "creator": { 219 | "id": 1049715943, 220 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTQzP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--aa4fa01aface7171cf769ff933e6defc921f6169", 221 | "name": "Beth Allen", 222 | "email_address": "beth@letobrand.com", 223 | "personable_type": "Client", 224 | "title": "Product Tactics Architect", 225 | "bio": null, 226 | "location": null, 227 | "created_at": "2022-11-22T08:23:22.345Z", 228 | "updated_at": "2022-11-22T08:23:22.345Z", 229 | "admin": false, 230 | "owner": false, 231 | "client": false, 232 | "employee": false, 233 | "time_zone": "Etc/UTC", 234 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBOdkkT4=--1d2b80e583133f93afe008f88166b674fc0287a4/avatar?v=1", 235 | "company": { 236 | "id": 1033447818, 237 | "name": "Leto Brand" 238 | }, 239 | "can_manage_projects": false, 240 | "can_manage_people": false 241 | }, 242 | "content": "
Looks great! Thanks for all your hard work on this.
", 243 | "approved": true 244 | } 245 | ] 246 | } 247 | ``` 248 | 249 | ###### Copy as cURL 250 | 251 | ``` shell 252 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/client/approvals/2.json 253 | ``` 254 | 255 | [pagination]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination 256 | -------------------------------------------------------------------------------- /sections/client_correspondences.md: -------------------------------------------------------------------------------- 1 | Client correspondences 2 | ====================== 3 | 4 | Endpoints: 5 | 6 | - [Get client correspondences](#get-client-correspondences) 7 | - [Get a client correspondence](#get-a-client-correspondence) 8 | 9 | Get client correspondences 10 | -------------------------- 11 | 12 | * `GET /buckets/1/client/correspondences.json` will return a [paginated list][pagination] of client correspondences in the project with an ID of `1`. 13 | 14 | ###### Example JSON Response 15 | 16 | ```json 17 | [ 18 | { 19 | "id": 1069479645, 20 | "status": "active", 21 | "visible_to_clients": false, 22 | "created_at": "2022-11-17T12:20:14.049Z", 23 | "updated_at": "2022-11-22T08:24:20.989Z", 24 | "title": "Final deliverables and launch are right around the corner", 25 | "inherits_status": true, 26 | "type": "Client::Correspondence", 27 | "url": "https://3.basecampapi.com/195539477/buckets/2085958500/client/correspondences/1069479645.json", 28 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958500/client/correspondences/1069479645", 29 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5NjQ1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--b97572c6fc1a6421db18970bedae2ed70392d269.json", 30 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958500/recordings/1069479645/subscription.json", 31 | "parent": { 32 | "id": 1069479564, 33 | "title": "The Clientside", 34 | "type": "Client::Board", 35 | "url": "https://3.basecampapi.com/195539477/buckets/2085958500/client/board.json", 36 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958500/client/board.1069479564" 37 | }, 38 | "bucket": { 39 | "id": 2085958500, 40 | "name": "The Leto Locator", 41 | "type": "Project" 42 | }, 43 | "creator": { 44 | "id": 1049715915, 45 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--aeb392ebf54ffd820e45f27add22bae3a8c7da56", 46 | "name": "Annie Bryan", 47 | "email_address": "annie@honchodesign.com", 48 | "personable_type": "User", 49 | "title": "Central Markets Manager", 50 | "bio": "To open a store is easy, to keep it open is an art", 51 | "location": null, 52 | "created_at": "2022-11-22T08:23:21.911Z", 53 | "updated_at": "2022-11-22T08:23:21.911Z", 54 | "admin": false, 55 | "owner": false, 56 | "client": false, 57 | "employee": true, 58 | "time_zone": "America/Chicago", 59 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMtkkT4=--9927c47a4cbee30a7f9aea667882496aba799149/avatar?v=1", 60 | "company": { 61 | "id": 1033447817, 62 | "name": "Honcho Design" 63 | }, 64 | "can_manage_projects": true, 65 | "can_manage_people": true 66 | }, 67 | "content": "
Hey everyone - we're in the home stretch! It's hard to believe how far we've come in just about 6 weeks. We've made incredible progress - created an in depth strategy and plan of attack, built an awesome experience and design, and backed it with incredible technology. We're so thrilled to be nearing the finish line - not just that we did it, but the way we did it.

\n\n Of course, we're not quite there yet so we don't want to start celebrating just yet . We're running through our final bug fixes and those should be done today. We'll want one more pass by legal to take a look. And then of course, one more eyeball from the Leto team. In fact, we're in such good shape, we could even launch the site as-is - it's really solid.

\n\n Please let us know if there's anything else on your minds before launch, but just wanted to report back that we're in good shape and on target to launch on schedule!
", 68 | "subject": "Final deliverables and launch are right around the corner", 69 | "replies_count": 5, 70 | "replies_url": "https://3.basecampapi.com/195539477/buckets/2085958500/client/recordings/1069479645/replies.json" 71 | } 72 | ] 73 | ``` 74 | 75 | ###### Copy as cURL 76 | 77 | ``` shell 78 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/client/correspondences.json 79 | ``` 80 | 81 | Get a client correspondence 82 | --------------------------- 83 | 84 | * `GET /buckets/1/client/correspondences/2.json` will return the client correspondence with an ID of `2` in the project with an ID of `1`. 85 | 86 | ###### Example JSON Response 87 | 88 | ```json 89 | { 90 | "id": 1069479566, 91 | "status": "active", 92 | "visible_to_clients": false, 93 | "created_at": "2022-10-09T09:22:14.049Z", 94 | "updated_at": "2022-11-22T08:24:14.926Z", 95 | "title": "Project kickoff!", 96 | "inherits_status": true, 97 | "type": "Client::Correspondence", 98 | "url": "https://3.basecampapi.com/195539477/buckets/2085958500/client/correspondences/1069479566.json", 99 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958500/client/correspondences/1069479566", 100 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5NTY2P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--fbfbc7c9428986404e1713f3335033f80b3c0313.json", 101 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958500/recordings/1069479566/subscription.json", 102 | "parent": { 103 | "id": 1069479564, 104 | "title": "The Clientside", 105 | "type": "Client::Board", 106 | "url": "https://3.basecampapi.com/195539477/buckets/2085958500/client/board.json", 107 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958500/client/board.1069479564" 108 | }, 109 | "bucket": { 110 | "id": 2085958500, 111 | "name": "The Leto Locator", 112 | "type": "Project" 113 | }, 114 | "creator": { 115 | "id": 1049715929, 116 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTI5P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--d5a066a78ea37eba00e6590336eb23dd6717760b", 117 | "name": "Jay Edmonds", 118 | "email_address": "jay@honchodesign.com", 119 | "personable_type": "User", 120 | "title": "Internal Marketing Assistant", 121 | "bio": null, 122 | "location": null, 123 | "created_at": "2022-11-22T08:23:22.092Z", 124 | "updated_at": "2022-11-22T08:23:22.092Z", 125 | "admin": false, 126 | "owner": false, 127 | "client": false, 128 | "employee": false, 129 | "time_zone": "Etc/UTC", 130 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBNlkkT4=--0f3c77d8c13069d514fd3f0ad694a67e426bad0f/avatar?v=1", 131 | "can_manage_projects": true, 132 | "can_manage_people": true 133 | }, 134 | "content": "
Hi everyone! Welcome to the Basecamp that we'll be using to collaboroate and manage the Leto Locator project.\n\n We're particularly excited to bring on board our friends from Leto - Stephen, Miranda, and Beth. I know you guys have used Basecamp before, but so we're on the same page, we'll post a bunch of discussions, things for review, and todos to make sure we stay on the same page. We'll do our best to keep everyone looped in this way, instead of using email (which can be hard to keep people up to date on stuff.)\n\n I also want to take a moment to introduce our team. It will be evolving and growing soon, but right now we've got some core team members: Myself as the Account Director, Annie as the Senior PM, Jared is our tech lead, Matt is our ACD, and Victor, of course, you know. A few people will be coming on to support us, but this will be your core team. You can, of course, reach out to any one of us at any time, but I'll ultimately be the one responsible for making sure you're happy with our work.\n\n Again, can't tell you how excited we are to get started on this and all the other projects. Let's go, Leto!\n\n -Jay
", 135 | "subject": "Project kickoff!", 136 | "replies_count": 5, 137 | "replies_url": "https://3.basecampapi.com/195539477/buckets/2085958500/client/recordings/1069479566/replies.json" 138 | } 139 | ``` 140 | 141 | ###### Copy as cURL 142 | 143 | ``` shell 144 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/client/correspondences/2.json 145 | ``` 146 | 147 | [pagination]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination 148 | -------------------------------------------------------------------------------- /sections/client_replies.md: -------------------------------------------------------------------------------- 1 | Client replies 2 | ============== 3 | 4 | Client replies are nested under the recording ID of a [client correspondence][correspondences] or [client approval][approvals]. 5 | 6 | Endpoints: 7 | 8 | - [Get client replies](#get-client-replies) 9 | - [Get a client reply](#get-a-client-reply) 10 | 11 | Get client replies 12 | ------------------ 13 | 14 | * `GET /buckets/1/client/recordings/2/replies.json` will return a [paginated list][pagination] of client replies in the project with an ID of `1` and the recording with ID of `2`. 15 | 16 | ###### Example JSON Response 17 | 18 | ```json 19 | [ 20 | { 21 | "id": 1069479567, 22 | "status": "active", 23 | "visible_to_clients": false, 24 | "created_at": "2022-10-09T10:36:14.049Z", 25 | "updated_at": "2022-10-09T10:36:14.049Z", 26 | "title": "Re: Project kickoff!", 27 | "inherits_status": true, 28 | "type": "Client::Reply", 29 | "url": "https://3.basecampapi.com/195539477/buckets/2085958500/client/replies/1069479567.json", 30 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958500/client/correspondences/1069479566#__recording_1069479567", 31 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5NTY3P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--9ff5d4f77619de8b3657b8b4fbe22e9d0b7c2b5a.json", 32 | "parent": { 33 | "id": 1069479566, 34 | "title": "Project kickoff!", 35 | "type": "Client::Correspondence", 36 | "url": "https://3.basecampapi.com/195539477/buckets/2085958500/client/correspondences/1069479566.json", 37 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958500/client/correspondences/1069479566" 38 | }, 39 | "bucket": { 40 | "id": 2085958500, 41 | "name": "The Leto Locator", 42 | "type": "Project" 43 | }, 44 | "creator": { 45 | "id": 1049715941, 46 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTQxP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--10099ab54fac5884db30b9bd897ea030023d4d0a", 47 | "name": "Stephen Early", 48 | "email_address": "stephen@letobrand.com", 49 | "personable_type": "Client", 50 | "title": "National Directives Director", 51 | "bio": null, 52 | "location": null, 53 | "created_at": "2022-11-22T08:23:22.341Z", 54 | "updated_at": "2022-11-22T08:23:22.341Z", 55 | "admin": false, 56 | "owner": false, 57 | "client": false, 58 | "employee": false, 59 | "time_zone": "Etc/UTC", 60 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBOVkkT4=--33e3fc268c87411378691c71b6f13658e0b40967/avatar?v=1", 61 | "company": { 62 | "id": 1033447818, 63 | "name": "Leto Brand" 64 | }, 65 | "can_manage_projects": false, 66 | "can_manage_people": false 67 | }, 68 | "content": "
Hi all - we're excited to get started too.
" 69 | } 70 | ] 71 | ``` 72 | 73 | ###### Copy as cURL 74 | 75 | ``` shell 76 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/client/recordings/2/replies.json 77 | ``` 78 | 79 | Get a client reply 80 | ------------------ 81 | 82 | * `GET /buckets/1/client/recordings/2/replies/3.json` will return the client reply with an ID of `3` for the recording with an ID of `2` in the project with an ID of `1`. 83 | 84 | ###### Example JSON Response 85 | 86 | ```json 87 | { 88 | "id": 1069479571, 89 | "status": "active", 90 | "visible_to_clients": false, 91 | "created_at": "2022-10-09T09:20:14.049Z", 92 | "updated_at": "2022-10-09T09:20:14.049Z", 93 | "title": "Re: Project kickoff!", 94 | "inherits_status": true, 95 | "type": "Client::Reply", 96 | "url": "https://3.basecampapi.com/195539477/buckets/2085958500/client/replies/1069479571.json", 97 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958500/client/correspondences/1069479566#__recording_1069479571", 98 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5NTcxP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--c711ae715330c9d458072698256fec0d86abd15e.json", 99 | "parent": { 100 | "id": 1069479566, 101 | "title": "Project kickoff!", 102 | "type": "Client::Correspondence", 103 | "url": "https://3.basecampapi.com/195539477/buckets/2085958500/client/correspondences/1069479566.json", 104 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958500/client/correspondences/1069479566" 105 | }, 106 | "bucket": { 107 | "id": 2085958500, 108 | "name": "The Leto Locator", 109 | "type": "Project" 110 | }, 111 | "creator": { 112 | "id": 1049715915, 113 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--aeb392ebf54ffd820e45f27add22bae3a8c7da56", 114 | "name": "Annie Bryan", 115 | "email_address": "annie@honchodesign.com", 116 | "personable_type": "User", 117 | "title": "Central Markets Manager", 118 | "bio": "To open a store is easy, to keep it open is an art", 119 | "location": null, 120 | "created_at": "2022-11-22T08:23:21.911Z", 121 | "updated_at": "2022-11-22T08:23:21.911Z", 122 | "admin": false, 123 | "owner": false, 124 | "client": false, 125 | "employee": true, 126 | "time_zone": "America/Chicago", 127 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMtkkT4=--9927c47a4cbee30a7f9aea667882496aba799149/avatar?v=1", 128 | "company": { 129 | "id": 1033447817, 130 | "name": "Honcho Design" 131 | }, 132 | "can_manage_projects": true, 133 | "can_manage_people": true 134 | }, 135 | "content": "
Hi Leto team, this it's Annie. I'll be your day to day contact for the project, so keep me on your speed dial (or speed email, perhaps more accurately!) Feel free to reach out to me with any questions at all, and I'll be posting up some outlines, timelines, etc. very shortly.
" 136 | } 137 | ``` 138 | 139 | ###### Copy as cURL 140 | 141 | ``` shell 142 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/client/recordings/2/replies/3.json 143 | ``` 144 | 145 | [pagination]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination 146 | [correspondences]: https://github.com/basecamp/bc3-api/blob/master/sections/client_correspondences.md#client-correspondences 147 | [approvals]: https://github.com/basecamp/bc3-api/blob/master/sections/client_approvals.md#client-approvals 148 | -------------------------------------------------------------------------------- /sections/client_visibility.md: -------------------------------------------------------------------------------- 1 | Client visibility 2 | ================= 3 | 4 | The client visibility refers to [the newer way to work with clients in Basecamp 4][1], and not to the _Clientside_, which is covered in its own sections: [approvals][2], [correspondences][3] and [replies][4]. 5 | 6 | Endpoints: 7 | 8 | - [Toggle client visibility](#toggle-client-visibility) 9 | 10 | Toggle client visibility 11 | ------------------------ 12 | 13 | * `PUT /buckets/1/recordings/2/client_visibility.json` allows changing the client visibility for the recording with an ID of `2` in the project with ID `1`. 14 | 15 | **Required parameter**: `visible_to_clients` with value `true` or `false`. 16 | 17 | This endpoint will return `200 OK` with the current JSON representation of the recording if the update was a success. Notice that not all recordings allow toggling client visibility, some inherit the visibility of their parent. For example, individual to-dos inherit the visibility of the to-do list they belong to. This endpoint will return `403 Forbidden` if the recording provided doesn't control its client visibility. 18 | 19 | ###### Example JSON Request 20 | 21 | ``` json 22 | { 23 | "visible_to_clients": true 24 | } 25 | ``` 26 | 27 | ###### Copy as cURL 28 | 29 | ``` shell 30 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 31 | -d '{"visible_to_clients":true}' -X PUT \ 32 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/recordings/2/client_visibility.json 33 | ``` 34 | 35 | [1]: https://m.signalvnoise.com/launch-a-brand-new-way-to-work-with-clients-in-basecamp-3-6a78b1175c5d 36 | [2]: https://github.com/basecamp/bc3-api/blob/master/sections/client_approvals.md 37 | [3]: https://github.com/basecamp/bc3-api/blob/master/sections/client_correspondences.md 38 | [4]: https://github.com/basecamp/bc3-api/blob/master/sections/client_replies.md 39 | -------------------------------------------------------------------------------- /sections/comments.md: -------------------------------------------------------------------------------- 1 | Comments 2 | ======== 3 | 4 | To determine if a resource can be commented on, check for the presences of `comments_count` and `comments_url` attributes in its JSON response. 5 | 6 | Endpoints: 7 | 8 | - [Get comments](#get-comments) 9 | - [Get a comment](#get-a-comment) 10 | - [Create a comment](#create-a-comment) 11 | - [Update a comment](#update-a-comment) 12 | - [Trash a comment][trash] 13 | 14 | Get comments 15 | ------------ 16 | 17 | * `GET /buckets/1/recordings/3/comments.json` will return a [paginated list][pagination] of active comments in the project with an ID of `1` and the recording with ID of `3`. 18 | 19 | ###### Example JSON Response 20 | 21 | ```json 22 | [ 23 | { 24 | "id": 1069479352, 25 | "status": "active", 26 | "visible_to_clients": false, 27 | "created_at": "2022-10-29T10:32:58.169Z", 28 | "updated_at": "2022-10-29T10:32:58.169Z", 29 | "title": "Re: We won Leto!", 30 | "inherits_status": true, 31 | "type": "Comment", 32 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/comments/1069479352.json", 33 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/messages/1069479351#__recording_1069479352", 34 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5MzUyP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--776378f4118807d7eea7c42ddd2a8ab6079b2788.json", 35 | "parent": { 36 | "id": 1069479351, 37 | "title": "We won Leto!", 38 | "type": "Message", 39 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/messages/1069479351.json", 40 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/messages/1069479351" 41 | }, 42 | "bucket": { 43 | "id": 2085958499, 44 | "name": "The Leto Laptop", 45 | "type": "Project" 46 | }, 47 | "creator": { 48 | "id": 1049715923, 49 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTIzP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--cc7313cd0fef7654f37f813c000bf892d80e2e2f", 50 | "name": "Andrew Wong", 51 | "email_address": "andrew@honchodesign.com", 52 | "personable_type": "User", 53 | "title": "Senior Branding Strategist", 54 | "bio": null, 55 | "location": null, 56 | "created_at": "2022-11-22T08:23:22.017Z", 57 | "updated_at": "2022-11-22T08:23:22.017Z", 58 | "admin": false, 59 | "owner": false, 60 | "client": false, 61 | "employee": false, 62 | "time_zone": "Etc/UTC", 63 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBNNkkT4=--e3c2676dde30e7c13f87642e3a3dd46ad657f731/avatar?v=1", 64 | "can_manage_projects": true, 65 | "can_manage_people": true 66 | }, 67 | "content": "
Yeah! Great job everyone! Super excited to get going!
" 68 | } 69 | ] 70 | ``` 71 | 72 | ###### Copy as cURL 73 | 74 | ``` shell 75 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/recordings/3/comments.json 76 | ``` 77 | 78 | 79 | Get a comment 80 | ------------- 81 | 82 | * `GET /buckets/1/comments/2.json` will return the comment with an ID of `2` in the project with an ID of `1`. 83 | 84 | ###### Example JSON Response 85 | 86 | ```json 87 | { 88 | "id": 1069479361, 89 | "status": "active", 90 | "visible_to_clients": false, 91 | "created_at": "2022-10-30T01:01:58.169Z", 92 | "updated_at": "2022-10-30T01:01:58.169Z", 93 | "title": "Re: We won Leto!", 94 | "inherits_status": true, 95 | "type": "Comment", 96 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/comments/1069479361.json", 97 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/messages/1069479351#__recording_1069479361", 98 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5MzYxP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--8b7691463c92f63fe45627584ed759b44fe7bdaa.json", 99 | "parent": { 100 | "id": 1069479351, 101 | "title": "We won Leto!", 102 | "type": "Message", 103 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/messages/1069479351.json", 104 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/messages/1069479351" 105 | }, 106 | "bucket": { 107 | "id": 2085958499, 108 | "name": "The Leto Laptop", 109 | "type": "Project" 110 | }, 111 | "creator": { 112 | "id": 1049715915, 113 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--aeb392ebf54ffd820e45f27add22bae3a8c7da56", 114 | "name": "Annie Bryan", 115 | "email_address": "annie@honchodesign.com", 116 | "personable_type": "User", 117 | "title": "Central Markets Manager", 118 | "bio": "To open a store is easy, to keep it open is an art", 119 | "location": null, 120 | "created_at": "2022-11-22T08:23:21.911Z", 121 | "updated_at": "2022-11-22T08:23:21.911Z", 122 | "admin": false, 123 | "owner": false, 124 | "client": false, 125 | "employee": true, 126 | "time_zone": "America/Chicago", 127 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMtkkT4=--9927c47a4cbee30a7f9aea667882496aba799149/avatar?v=1", 128 | "company": { 129 | "id": 1033447817, 130 | "name": "Honcho Design" 131 | }, 132 | "can_manage_projects": true, 133 | "can_manage_people": true 134 | }, 135 | "content": "
I just want to echo what just about everyone already said. This is a big one for us, and I can't wait to get going. I'll be spinning up the project shortly!
" 136 | } 137 | ``` 138 | 139 | ###### Copy as cURL 140 | 141 | ``` shell 142 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/comment/2.json 143 | ``` 144 | 145 | 146 | Create a comment 147 | ---------------- 148 | 149 | * `POST /buckets/1/recordings/3/comments.json` publishes a comment in the project with ID `1` and under the recording with an ID of `3`. 150 | 151 | **Required parameters**: `content` as the body of the message. See our [Rich text guide][rich] for what HTML tags are allowed. 152 | 153 | Note: All people who are subscribed to the recording will be notified when the comment is posted. 154 | 155 | This endpoint will return `201 Created` with the current JSON representation of the message if the creation was a success. See the [Get a comment](#get-a-comment) endpoint for more info on the payload. The `Location` header will contain a URL to the HTML version of the new comment. 156 | 157 | ###### Example JSON Request 158 | 159 | ``` json 160 | { 161 | "content": "
Wow! That is cool.
", 162 | } 163 | ``` 164 | 165 | ###### Copy as cURL 166 | 167 | ``` shell 168 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 169 | -d '{"content":"
Wow! That is cool.
"}' \ 170 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/recordings/3/comments.json 171 | ``` 172 | 173 | 174 | Update a comment 175 | ---------------- 176 | 177 | * `PUT /buckets/1/comments/2.json` allows changing content of the message with an ID of `2` in the project with ID `1`. 178 | 179 | This endpoint will return `200 OK` with the current JSON representation of the message if the update was a success. See the [Get a comment](#get-a-comment) endpoint for more info on the payload. The `Location` header will contain a URL to the HTML version of the updated comment. 180 | 181 | ###### Example JSON Request 182 | 183 | ``` json 184 | { 185 | "content": "
No way! That isn't cool at all.
" 186 | } 187 | ``` 188 | 189 | ###### Copy as cURL 190 | 191 | ``` shell 192 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 193 | -d '{"content":"
No way! That isn't cool at all.
"}' -X PUT \ 194 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/messages/2.json 195 | ``` 196 | 197 | 198 | [recordings]: https://github.com/basecamp/bc3-api/blob/master/sections/recordings.md#recordings 199 | [messages]: https://github.com/basecamp/bc3-api/blob/master/sections/messages.md#messages 200 | [todolists]: https://github.com/basecamp/bc3-api/blob/master/sections/todolists.md#todolists 201 | [todos]: https://github.com/basecamp/bc3-api/blob/master/sections/todos.md#todos 202 | [trash]: https://github.com/basecamp/bc3-api/blob/master/sections/recordings.md#trash-a-recording 203 | [pagination]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination 204 | [rich]: https://github.com/basecamp/bc3-api/blob/master/README.md#rich-text-content 205 | -------------------------------------------------------------------------------- /sections/forwards.md: -------------------------------------------------------------------------------- 1 | Forwards 2 | ======== 3 | 4 | Endpoints: 5 | 6 | - [Get forwards](#get-forwards) 7 | - [Get a forward](#get-a-forward) 8 | - [Trash a forward][1] 9 | 10 | 11 | Get forwards 12 | ------------ 13 | 14 | * `GET /buckets/1/inboxes/3/forwards.json` will return a [paginated list][2] of active forwards in the project with an ID of `1` and the inbox with an ID of `3`. 15 | 16 | To get the inbox ID for a project, see the [Get inbox][3] endpoint. 17 | 18 | ###### Example JSON Response 19 | 20 | ```json 21 | [ 22 | { 23 | "id": 1069479031, 24 | "status": "active", 25 | "visible_to_clients": false, 26 | "created_at": "2022-09-01T10:16:24.930Z", 27 | "updated_at": "2022-09-01T10:16:24.930Z", 28 | "title": "Fwd: Some technical details", 29 | "inherits_status": true, 30 | "type": "Inbox::Forward", 31 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/inbox_forwards/1069479031.json", 32 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/inbox_forwards/1069479031", 33 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5MDMxP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--4891627f80344c55f5a27c306dff50d689e6cbf1.json", 34 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958497/recordings/1069479031/subscription.json", 35 | "parent": { 36 | "id": 1069478936, 37 | "title": "Email Forwards", 38 | "type": "Inbox", 39 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/inboxes/1069478936.json", 40 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/inboxes/1069478936" 41 | }, 42 | "bucket": { 43 | "id": 2085958497, 44 | "name": "Honcho Design Newsroom", 45 | "type": "Project" 46 | }, 47 | "creator": { 48 | "id": 1049715915, 49 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--aeb392ebf54ffd820e45f27add22bae3a8c7da56", 50 | "name": "Annie Bryan", 51 | "email_address": "annie@honchodesign.com", 52 | "personable_type": "User", 53 | "title": "Central Markets Manager", 54 | "bio": "To open a store is easy, to keep it open is an art", 55 | "location": null, 56 | "created_at": "2022-11-22T08:23:21.911Z", 57 | "updated_at": "2022-11-22T08:23:21.911Z", 58 | "admin": false, 59 | "owner": false, 60 | "client": false, 61 | "employee": true, 62 | "time_zone": "America/Chicago", 63 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMtkkT4=--9927c47a4cbee30a7f9aea667882496aba799149/avatar?v=1", 64 | "company": { 65 | "id": 1033447817, 66 | "name": "Honcho Design" 67 | }, 68 | "can_manage_projects": true, 69 | "can_manage_people": true 70 | }, 71 | "content": "---------- Forwarded message ----------\nFrom: \"Beth Allen\" \nDate: Oct 13, 2013 1:38 PM\nSubject: Some technical details\nTo: \"Annie Bryan\" \n\nHey Team Honcho,\n\nJust wanted to let you know I'm a big fan of your blog. Your writing is so inspiring. Thanks for sharing!", 72 | "subject": "Fwd: Some technical details", 73 | "from": "beth@letobrand.com", 74 | "replies_count": 0, 75 | "replies_url": "https://3.basecampapi.com/195539477/buckets/2085958497/inbox_forwards/1069479031/replies.json" 76 | } 77 | ] 78 | ``` 79 | 80 | 81 | ###### Copy as cURL 82 | 83 | ``` shell 84 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/inboxes/3/forwards.json 85 | ``` 86 | 87 | 88 | Get a forward 89 | ------------- 90 | 91 | * `GET /buckets/1/inbox_forwards/2.json` will return the forward with an ID of `2` in the project with an ID of `1`. 92 | 93 | ###### Example JSON Response 94 | 95 | ```json 96 | { 97 | "id": 1069479032, 98 | "status": "active", 99 | "visible_to_clients": false, 100 | "created_at": "2022-09-01T09:04:24.930Z", 101 | "updated_at": "2022-11-22T08:23:32.496Z", 102 | "title": "Fwd: Can we make the logo pop?", 103 | "inherits_status": true, 104 | "type": "Inbox::Forward", 105 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/inbox_forwards/1069479032.json", 106 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/inbox_forwards/1069479032", 107 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5MDMyP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--22643a88456d69fada6fdb7e215bdc16aaa20b84.json", 108 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958497/recordings/1069479032/subscription.json", 109 | "parent": { 110 | "id": 1069478936, 111 | "title": "Email Forwards", 112 | "type": "Inbox", 113 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/inboxes/1069478936.json", 114 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/inboxes/1069478936" 115 | }, 116 | "bucket": { 117 | "id": 2085958497, 118 | "name": "Honcho Design Newsroom", 119 | "type": "Project" 120 | }, 121 | "creator": { 122 | "id": 1049715914, 123 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 124 | "name": "Victor Cooper", 125 | "email_address": "victor@honchodesign.com", 126 | "personable_type": "User", 127 | "title": "Chief Strategist", 128 | "bio": "Don’t let your dreams be dreams", 129 | "location": "Chicago, IL", 130 | "created_at": "2022-11-22T08:23:21.732Z", 131 | "updated_at": "2022-11-22T08:23:21.904Z", 132 | "admin": true, 133 | "owner": true, 134 | "client": false, 135 | "employee": true, 136 | "time_zone": "America/Chicago", 137 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 138 | "company": { 139 | "id": 1033447817, 140 | "name": "Honcho Design" 141 | }, 142 | "can_manage_projects": true, 143 | "can_manage_people": true 144 | }, 145 | "content": "---------- Forwarded message ----------\nFrom: \"Henry Bowman\" \nDate: Oct 15, 2013 1:13 AM\nSubject: Can we make the logo pop?\nTo: \"Victor Cooper\" \n\nHey Victor,\n\nI know it's late at night, but I had a quick thought about the logo. It feels, I dunno, flat. Is there anything you could do to make it pop? I'm thinking it needs more sizzle. More... SOMETHING. Maybe we could try adding a rainbow?\n\nLet's take a look mid-day tomorrow and re-group with the rest of the team.\n\nCheers,\nHenry", 146 | "subject": "Fwd: Can we make the logo pop?", 147 | "from": "henry@letobrand.com", 148 | "replies_count": 2, 149 | "replies_url": "https://3.basecampapi.com/195539477/buckets/2085958497/inbox_forwards/1069479032/replies.json" 150 | } 151 | ``` 152 | 153 | 154 | ###### Copy as cURL 155 | 156 | ``` shell 157 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/inbox_forwards/2.json 158 | ``` 159 | 160 | 161 | [1]: https://github.com/basecamp/bc3-api/blob/master/sections/recordings.md#trash-a-recording 162 | [2]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination 163 | [3]: https://github.com/basecamp/bc3-api/blob/master/sections/inboxes.md#inboxes 164 | -------------------------------------------------------------------------------- /sections/inbox_replies.md: -------------------------------------------------------------------------------- 1 | Inbox replies 2 | ============== 3 | 4 | Inbox replies are nested under the recording ID of a [forward][forwards]. 5 | 6 | Endpoints: 7 | 8 | - [Get inbox replies](#get-inbox-replies) 9 | - [Get an inbox reply](#get-an-inbox-reply) 10 | 11 | Get inbox replies 12 | ------------------- 13 | 14 | * `GET /buckets/1/inbox_forwards/2/replies.json` will return a [paginated list][pagination] of inbox replies in the project with an ID of `1` and the forward with ID of `2`. 15 | 16 | ###### Example JSON Response 17 | 18 | ```json 19 | [ 20 | { 21 | "id": 1660382161, 22 | "status": "active", 23 | "visible_to_clients": true, 24 | "created_at": "2019-03-14T09:17:34.481Z", 25 | "updated_at": "2019-03-14T09:17:34.498Z", 26 | "title": "Re: Project kickoff!", 27 | "inherits_status": true, 28 | "type": "Inbox::Reply", 29 | "url": "https://3.basecampapi.com/3714590/buckets/6883364/inbox_replies/1660382161.json", 30 | "app_url": "https://3.basecamp.com/3714590/buckets/6883364/inbox_forwards/1660377455#__recording_1660382161", 31 | "bookmark_url": "https://3.basecampapi.com/3714590/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xNjYwMzgyMTYxP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--a3d7a6039ae477980c497c0d3d96ee7c16d45a06.json", 32 | "parent": { 33 | "id": 1660377455, 34 | "title": "Project kickoff!", 35 | "type": "Inbox::Forward", 36 | "url": "https://3.basecampapi.com/3714590/buckets/6883364/inbox_forwards/1660377455.json", 37 | "app_url": "https://3.basecamp.com/3714590/buckets/6883364/inbox_forwards/1660377455" 38 | }, 39 | "bucket": { 40 | "id": 6883364, 41 | "name": "The Leto Laptop project", 42 | "type": "Project" 43 | }, 44 | "creator": { 45 | "id": 11347030, 46 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIpZ2lkOi8vYmMzL1BlcnNvbi8xMTM0NzAzMD9leHBpcmVzX2luBjsAVEkiDHB1cnBvc2UGOwBUSSIPYXR0YWNoYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--b3910c4b417b73361601f8d2df454b526e9fc300", 47 | "name": "Stephen Early", 48 | "email_address": "stephen@letobrand.com", 49 | "personable_type": "User", 50 | "title": "", 51 | "bio": "", 52 | "created_at": "2017-04-04T20:27:07.226Z", 53 | "updated_at": "2019-03-12T10:58:16.269Z", 54 | "admin": true, 55 | "owner": true, 56 | "client": false, 57 | "time_zone": "Europe/Madrid", 58 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBGIqCjw=--30a34b0522d7ba3484b8c4dcd65d9087a1baef0e/avatar-64-x4", 59 | "company": { 60 | "id": 1033447818, 61 | "name": "Leto Brand" 62 | } 63 | }, 64 | "content": "
Looking great!
" 65 | } 66 | ] 67 | ``` 68 | 69 | ###### Copy as cURL 70 | 71 | ``` shell 72 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/inbox_forwards/2/replies.json 73 | ``` 74 | 75 | Get an inbox reply 76 | ------------------- 77 | 78 | * `GET /buckets/1/inbox_forwards/2/replies/3.json` will return the inbox reply with an ID of `3` for the forward with an ID of `2` in the project with an ID of `1`. 79 | 80 | ###### Example JSON Response 81 | 82 | ```json 83 | { 84 | "id": 1660382161, 85 | "status": "active", 86 | "visible_to_clients": true, 87 | "created_at": "2019-03-14T09:17:34.481Z", 88 | "updated_at": "2019-03-14T09:17:34.498Z", 89 | "title": "Re: Project kickoff!", 90 | "inherits_status": true, 91 | "type": "Inbox::Reply", 92 | "url": "https://3.basecampapi.com/3714590/buckets/6883364/inbox_replies/1660382161.json", 93 | "app_url": "https://3.basecamp.com/3714590/buckets/6883364/inbox_forwards/1660377455#__recording_1660382161", 94 | "bookmark_url": "https://3.basecampapi.com/3714590/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xNjYwMzgyMTYxP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--a3d7a6039ae477980c497c0d3d96ee7c16d45a06.json", 95 | "parent": { 96 | "id": 1660377455, 97 | "title": "Project kickoff!", 98 | "type": "Inbox::Forward", 99 | "url": "https://3.basecampapi.com/3714590/buckets/6883364/inbox_forwards/1660377455.json", 100 | "app_url": "https://3.basecamp.com/3714590/buckets/6883364/inbox_forwards/1660377455" 101 | }, 102 | "bucket": { 103 | "id": 6883364, 104 | "name": "The Leto Laptop project", 105 | "type": "Project" 106 | }, 107 | "creator": { 108 | "id": 11347030, 109 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIpZ2lkOi8vYmMzL1BlcnNvbi8xMTM0NzAzMD9leHBpcmVzX2luBjsAVEkiDHB1cnBvc2UGOwBUSSIPYXR0YWNoYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--b3910c4b417b73361601f8d2df454b526e9fc300", 110 | "name": "Stephen Early", 111 | "email_address": "stephen@letobrand.com", 112 | "personable_type": "User", 113 | "title": "", 114 | "bio": "", 115 | "created_at": "2017-04-04T20:27:07.226Z", 116 | "updated_at": "2019-03-12T10:58:16.269Z", 117 | "admin": true, 118 | "owner": true, 119 | "client": false, 120 | "time_zone": "Europe/Madrid", 121 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBGIqCjw=--30a34b0522d7ba3484b8c4dcd65d9087a1baef0e/avatar-64-x4", 122 | "company": { 123 | "id": 1033447818, 124 | "name": "Leto Brand" 125 | } 126 | }, 127 | "content": "
Looking great!
" 128 | } 129 | ``` 130 | 131 | ###### Copy as cURL 132 | 133 | ``` shell 134 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/inbox_forwards/2/replies/3.json 135 | ``` 136 | 137 | [pagination]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination 138 | [forwards]: https://github.com/basecamp/bc3-api/blob/master/sections/forwards.md#forwards 139 | -------------------------------------------------------------------------------- /sections/inboxes.md: -------------------------------------------------------------------------------- 1 | Inboxes 2 | ======= 3 | 4 | All forwards in a project are children of an Inbox resource. 5 | 6 | Endpoints: 7 | 8 | - [Get inbox](#get-inbox) 9 | 10 | 11 | Get inbox 12 | --------- 13 | 14 | * `GET /buckets/1/inboxes/2.json` will return the inbox with an ID of `2` for the project with an ID of `1`. 15 | 16 | To get the inbox ID for a project, see the [Get a project][1] endpoint's `dock` payload. To retrieve its forwards, see the [Get forwards][2] endpoint. 17 | 18 | ###### Example JSON Response 19 | 20 | ```json 21 | { 22 | "id": 1069478936, 23 | "status": "active", 24 | "visible_to_clients": false, 25 | "created_at": "2022-11-22T08:23:25.010Z", 26 | "updated_at": "2022-11-22T08:23:32.501Z", 27 | "title": "Email Forwards", 28 | "inherits_status": true, 29 | "type": "Inbox", 30 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/inboxes/1069478936.json", 31 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/inboxes/1069478936", 32 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc4OTM2P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--02c84e4d8421bf89b7325129cbdabce35ac11eaf.json", 33 | "position": 6, 34 | "bucket": { 35 | "id": 2085958497, 36 | "name": "Honcho Design Newsroom", 37 | "type": "Project" 38 | }, 39 | "creator": { 40 | "id": 1049715914, 41 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 42 | "name": "Victor Cooper", 43 | "email_address": "victor@honchodesign.com", 44 | "personable_type": "User", 45 | "title": "Chief Strategist", 46 | "bio": "Don’t let your dreams be dreams", 47 | "location": "Chicago, IL", 48 | "created_at": "2022-11-22T08:23:21.732Z", 49 | "updated_at": "2022-11-22T08:23:21.904Z", 50 | "admin": true, 51 | "owner": true, 52 | "client": false, 53 | "employee": true, 54 | "time_zone": "America/Chicago", 55 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 56 | "company": { 57 | "id": 1033447817, 58 | "name": "Honcho Design" 59 | }, 60 | "can_manage_projects": true, 61 | "can_manage_people": true 62 | }, 63 | "forwards_count": 2, 64 | "forwards_url": "https://3.basecampapi.com/195539477/buckets/2085958497/inboxes/1069478936/forwards.json" 65 | } 66 | ``` 67 | 68 | 69 | ###### Copy as cURL 70 | 71 | ``` shell 72 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/inboxes/2.json 73 | ``` 74 | 75 | 76 | [1]: https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#get-a-project 77 | [2]: https://github.com/basecamp/bc3-api/blob/master/sections/forwards.md#get-forwards 78 | -------------------------------------------------------------------------------- /sections/lineup_markers.md: -------------------------------------------------------------------------------- 1 | Lineup Markers 2 | ================ 3 | 4 | Endpoints: 5 | 6 | - [Create a marker](#create-a-marker) 7 | - [Update a marker](#update-a-marker) 8 | - [Destroy a marker](#destroy-a-step) 9 | 10 | Create a marker 11 | ------------------------- 12 | 13 | * `POST /lineup/markers.json` creates an account wide marker that shows up in the Lineup. 14 | 15 | **Required parameters**: 16 | 17 | * `name` of the marker. 18 | * `date` of the marker iso8601 formatted without a time part. 19 | 20 | This endpoint will return `201 Created` with an empty response body. 21 | 22 | ###### Example JSON Request 23 | 24 | ``` json 25 | { 26 | "name": "Anniversary", 27 | "date": "2021-01-01" 28 | } 29 | ``` 30 | 31 | ###### Copy as cURL 32 | 33 | ``` shell 34 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 35 | -d '{"name": "Anniversary", "date": "2021-01-01"}' \ 36 | https://3.basecampapi.com/$ACCOUNT_ID/lineup/markers.json 37 | ``` 38 | 39 | Update a marker 40 | ----------------------- 41 | 42 | * `PUT /lineup/markers/1.json` change name and/or date of the marker with an ID of `1`. 43 | 44 | _Optional parameters_: 45 | 46 | * `name` of the marker. 47 | * `date` of the marker iso8601 formatted without a time part. 48 | 49 | This endpoint will return `200 OK` with an empty response body. 50 | 51 | ###### Example JSON Request 52 | 53 | ``` json 54 | { 55 | "name": "Updated anniversary" 56 | } 57 | ``` 58 | 59 | ###### Copy as cURL 60 | 61 | ``` shell 62 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 63 | -d '{"name": "Updated anniversary"}' -X PUT \ 64 | https://3.basecampapi.com/$ACCOUNT_ID/lineup/markers/1.json 65 | ``` 66 | 67 | Destroy a marker 68 | ----------------------- 69 | 70 | * `DELETE /lineup/markers/1.json` permanently destroys the marker with an ID of `1` immediately. 71 | 72 | This endpoint will return `204 No Content`. 73 | 74 | ###### Copy as cURL 75 | 76 | ``` shell 77 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 78 | -X DELETE \ 79 | https://3.basecampapi.com/$ACCOUNT_ID/lineup/markers/1.json 80 | ``` 81 | -------------------------------------------------------------------------------- /sections/message_boards.md: -------------------------------------------------------------------------------- 1 | Message Boards 2 | ============== 3 | 4 | All messages under a project are children of a Message Board resource. 5 | 6 | Endpoints: 7 | 8 | - [Get message board](#get-message-board) 9 | 10 | 11 | Get message board 12 | ----------------- 13 | 14 | * `GET /buckets/1/message_boards/2.json` will return the message board for the project with an ID of `1` and the message board ID of `2`. 15 | 16 | To get the message board ID for a project, see the [Get a project][1] endpoint's `dock` payload. To retrieve its messages, see the [Get messages][2] endpoint. 17 | 18 | ###### Example JSON Response 19 | 20 | ```json 21 | { 22 | "id": 1069479338, 23 | "status": "active", 24 | "visible_to_clients": false, 25 | "created_at": "2022-11-22T08:23:58.186Z", 26 | "updated_at": "2022-11-22T17:53:36.294Z", 27 | "title": "Message Board", 28 | "inherits_status": true, 29 | "type": "Message::Board", 30 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/message_boards/1069479338.json", 31 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/message_boards/1069479338", 32 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5MzM4P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--b1fc49d3c71b863b1635683193ce19eb723e7674.json", 33 | "position": 1, 34 | "bucket": { 35 | "id": 2085958499, 36 | "name": "The Leto Laptop", 37 | "type": "Project" 38 | }, 39 | "creator": { 40 | "id": 1049715914, 41 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 42 | "name": "Victor Cooper", 43 | "email_address": "victor@honchodesign.com", 44 | "personable_type": "User", 45 | "title": "Chief Strategist", 46 | "bio": "Don’t let your dreams be dreams", 47 | "location": "Chicago, IL", 48 | "created_at": "2022-11-22T08:23:21.732Z", 49 | "updated_at": "2022-11-22T08:23:21.904Z", 50 | "admin": true, 51 | "owner": true, 52 | "client": false, 53 | "employee": true, 54 | "time_zone": "America/Chicago", 55 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 56 | "company": { 57 | "id": 1033447817, 58 | "name": "Honcho Design" 59 | }, 60 | "can_manage_projects": true, 61 | "can_manage_people": true 62 | }, 63 | "messages_count": 9, 64 | "messages_url": "https://3.basecampapi.com/195539477/buckets/2085958499/message_boards/1069479338/messages.json", 65 | "app_messages_url": "https://3.basecamp.com/195539477/buckets/2085958499/message_boards/1069479338/messages" 66 | } 67 | ``` 68 | 69 | ###### Copy as cURL 70 | 71 | ``` shell 72 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/message_boards/2.json 73 | ``` 74 | 75 | 76 | [1]: https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#get-a-project 77 | [2]: https://github.com/basecamp/bc3-api/blob/master/sections/messages.md#get-messages 78 | [3]: https://github.com/basecamp/bc3-api/blob/master/sections/recordings.md#trash-a-recording 79 | -------------------------------------------------------------------------------- /sections/message_types.md: -------------------------------------------------------------------------------- 1 | Message Types 2 | ============= 3 | 4 | Endpoints: 5 | 6 | - [Get message types](#get-message-types) 7 | - [Get a message type](#get-a-message-type) 8 | - [Create a message type](#create-a-message-type) 9 | - [Update a message type](#update-a-message-type) 10 | - [Destroy a message type](#destroy-a-message-type) 11 | 12 | Get message types 13 | ----------------- 14 | 15 | * `GET /buckets/1/categories.json` will return a list of all the message types in the project with an ID of `1`. 16 | 17 | ###### Example JSON Response 18 | 19 | ```json 20 | [ 21 | { 22 | "id": 823758531, 23 | "name": "Announcement", 24 | "icon": "📢", 25 | "created_at": "2017-03-28T15:25:09.455Z", 26 | "updated_at": "2017-03-28T15:25:09.455Z" 27 | }, 28 | { 29 | "id": 823758530, 30 | "name": "Update", 31 | "icon": "❤️", 32 | "created_at": "2017-03-28T15:25:09.450Z", 33 | "updated_at": "2017-03-28T15:25:09.450Z" 34 | } 35 | ] 36 | ``` 37 | 38 | 39 | ###### Copy as cURL 40 | 41 | ``` shell 42 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/categories.json 43 | ``` 44 | 45 | Get a message type 46 | ------------------ 47 | 48 | * `GET /buckets/1/categories/2.json` will return the message type with ID `2` in the project with ID `1`. 49 | 50 | ###### Example JSON Response 51 | 52 | ```json 53 | { 54 | "id": 823758531, 55 | "name": "Announcement", 56 | "icon": "📢", 57 | "created_at": "2017-03-28T15:25:09.455Z", 58 | "updated_at": "2017-03-28T15:25:09.455Z" 59 | } 60 | ``` 61 | 62 | 63 | ###### Copy as cURL 64 | 65 | ``` shell 66 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/categories/2.json 67 | ``` 68 | 69 | Create a message type 70 | --------------------- 71 | 72 | * `POST /buckets/1/categories.json` creates a new message type in the project with ID `1`. 73 | 74 | **Required parameters**: `name` and `icon` for the new message type. 75 | 76 | This endpoint will return `201 Created` with the current JSON representation of the message type if the creation was a success. See the [Get a message type](#get-a-message-type) endpoint for more info on the payload. 77 | 78 | ###### Example JSON Request 79 | 80 | ``` json 81 | { 82 | "name": "Announcement", 83 | "icon": "📢" 84 | } 85 | ``` 86 | 87 | ###### Copy as cURL 88 | 89 | ``` shell 90 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 91 | -d '{"name":"Announcement","icon": "📢"}' \ 92 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/categories.json 93 | ``` 94 | 95 | Update a message type 96 | --------------------- 97 | 98 | * `PUT /buckets/1/categories/2.json` allows changing the message type with an ID of `2` in the project with ID `1`. 99 | 100 | This endpoint will return `200 OK` with the current JSON representation of the message type if the update was a success. See the [Get a message type](#get-a-message-type) endpoint for more info on the payload. 101 | 102 | ###### Example JSON Request 103 | 104 | ``` json 105 | { 106 | "name": "Quick Update", 107 | "icon": "📢" 108 | } 109 | ``` 110 | 111 | ###### Copy as cURL 112 | 113 | ``` shell 114 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 115 | -d '{"name":"Quick Update","icon":"📢"}' -X PUT \ 116 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/categories/2.json 117 | ``` 118 | 119 | Destroy a message type 120 | ---------------------- 121 | 122 | * `DELETE /buckets/1/categories/2.json` will delete the message type with an ID of `2`in the project with ID `1`. 123 | 124 | No parameters required. Returns `204 No Content` if successful. 125 | 126 | ###### Copy as cURL 127 | 128 | ``` shell 129 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -X DELETE \ 130 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/categories/2.json 131 | ``` 132 | -------------------------------------------------------------------------------- /sections/people.md: -------------------------------------------------------------------------------- 1 | People 2 | ====== 3 | 4 | Endpoints: 5 | 6 | - [Get all people](#get-all-people) 7 | - [Get people on a project](#get-people-on-a-project) 8 | - [Update who can access a project](#update-who-can-access-a-project) 9 | - [Get pingable people](#get-pingable-people) 10 | - [Get person](#get-person) 11 | - [Get my personal info](#get-my-personal-info) 12 | 13 | Get all people 14 | -------------- 15 | 16 | * `GET /people.json` will return all people visible to the current user. 17 | 18 | ###### Example JSON Response 19 | 20 | ```json 21 | [ 22 | { 23 | "id": 1049715914, 24 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 25 | "name": "Victor Cooper", 26 | "email_address": "victor@honchodesign.com", 27 | "personable_type": "User", 28 | "title": "Chief Strategist", 29 | "bio": "Don’t let your dreams be dreams", 30 | "location": "Chicago, IL", 31 | "created_at": "2022-11-22T08:23:21.732Z", 32 | "updated_at": "2022-11-22T08:23:21.904Z", 33 | "admin": true, 34 | "owner": true, 35 | "client": false, 36 | "employee": true, 37 | "time_zone": "America/Chicago", 38 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 39 | "company": { 40 | "id": 1033447817, 41 | "name": "Honcho Design" 42 | }, 43 | "can_manage_projects": true, 44 | "can_manage_people": true 45 | } 46 | ] 47 | ``` 48 | 49 | ###### Copy as cURL 50 | 51 | ``` shell 52 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/people.json 53 | ``` 54 | 55 | 56 | Get people on a project 57 | ------------------------ 58 | 59 | * `GET /projects/1/people.json` will return all active people on the project with the given ID. 60 | 61 | See the [Get all people](#get-all-people) endpoint for an example of the JSON response. 62 | 63 | ###### Copy as cURL 64 | 65 | ``` shell 66 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/projects/1/people.json 67 | ``` 68 | 69 | Update who can access a project 70 | -------------------------------- 71 | 72 | * `PUT /projects/1/people/users.json` allows granting new and existing people access to a project, and revoking access from existing people. 73 | 74 | **Parameters**: Requests should include at least one of the following parameters. 75 | 76 | * `grant` - an array of people IDs. 77 | * `revoke` - an array of people IDs. 78 | * `create` - an array of new people with `name` and `email_address` properties, and optional `title` and `company_name` properties. 79 | 80 | ###### Example JSON Request 81 | 82 | ```json 83 | { 84 | "grant": [ 85 | 1049715922 86 | ], 87 | "revoke": [ 88 | 1049715921 89 | ], 90 | "create": [ 91 | { 92 | "name": "Victor Copper", 93 | "email_address": "victor@hanchodesign.com", 94 | "title": "Prankster", 95 | "company_name": "Hancho Design" 96 | } 97 | ] 98 | } 99 | ``` 100 | 101 | ###### Copy as cURL 102 | 103 | ``` shell 104 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 105 | -d '{"grant":[2],"revoke":[3,4]}' -X PUT \ 106 | https://3.basecampapi.com/$ACCOUNT_ID/projects/1/people/users.json 107 | ``` 108 | 109 | ###### Example JSON Response 110 | 111 | ```json 112 | { 113 | "granted": [ 114 | { 115 | "id": 1049715922, 116 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTIyP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--90ea53b2b0ce32a96bcc6ef712c1fac0dbb0a0cd", 117 | "name": "Amy Rivera", 118 | "email_address": "amy@honchodesign.com", 119 | "personable_type": "User", 120 | "title": "Central Web Coordinator", 121 | "bio": "I never said most of the things I said", 122 | "location": null, 123 | "created_at": "2022-11-22T08:23:22.005Z", 124 | "updated_at": "2022-11-22T08:23:22.005Z", 125 | "admin": false, 126 | "owner": false, 127 | "client": false, 128 | "employee": false, 129 | "time_zone": "Etc/UTC", 130 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBNJkkT4=--6ef93d58440c2ed1fec4457e3eb5f09572e866a4/avatar?v=1", 131 | "can_manage_projects": true, 132 | "can_manage_people": true 133 | }, 134 | { 135 | "id": 1049715969, 136 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTY5P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--f94940da9b0adc1ec997382934419905904c8692", 137 | "name": "Victor Copper", 138 | "email_address": "victor@hanchodesign.com", 139 | "personable_type": "User", 140 | "title": "Prankster", 141 | "bio": null, 142 | "location": null, 143 | "created_at": "2022-11-22T17:56:23.633Z", 144 | "updated_at": "2022-11-22T17:56:23.633Z", 145 | "admin": false, 146 | "owner": false, 147 | "client": false, 148 | "employee": false, 149 | "time_zone": "America/Chicago", 150 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBAFlkT4=--b48efd42c6425ae51e7205e157d902971934e5b8/avatar?v=1", 151 | "company": { 152 | "id": 1033447819, 153 | "name": "Hancho Design" 154 | }, 155 | "can_manage_projects": true, 156 | "can_manage_people": true 157 | } 158 | ], 159 | "revoked": [ 160 | { 161 | "id": 1049715921, 162 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTIxP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--61b488a9fa97d2e628aee86cf51a4ba0171888c2", 163 | "name": "Steve Marsh", 164 | "email_address": "steve@honchodesign.com", 165 | "personable_type": "User", 166 | "title": "Legacy Directives Strategist", 167 | "bio": "You can do it!", 168 | "location": null, 169 | "created_at": "2022-11-22T08:23:21.991Z", 170 | "updated_at": "2022-11-22T08:23:21.991Z", 171 | "admin": false, 172 | "owner": false, 173 | "client": false, 174 | "employee": true, 175 | "time_zone": "Etc/UTC", 176 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBNFkkT4=--c57bba9b44447be39d4a79a5e7f2a592cae9e82c/avatar?v=1", 177 | "company": { 178 | "id": 1033447817, 179 | "name": "Honcho Design" 180 | }, 181 | "can_manage_projects": true, 182 | "can_manage_people": true 183 | } 184 | ] 185 | } 186 | ``` 187 | 188 | 189 | Get pingable people 190 | ------------------- 191 | 192 | * `GET /circles/people.json` will return all people on this Basecamp account who can be pinged. 193 | 194 | See the [Get all people](#get-all-people) endpoint for an example of the JSON response. 195 | 196 | **Note:** This endpoint is currently not paginated. 197 | 198 | ###### Copy as cURL 199 | 200 | ``` shell 201 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/circles/people.json 202 | ``` 203 | 204 | 205 | Get person 206 | ---------- 207 | 208 | * `GET /people/2.json` will return the profile for the user with the given ID. 209 | 210 | ###### Example JSON Response 211 | 212 | ```json 213 | { 214 | "id": 1049715927, 215 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTI3P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--91fc84e70b851466d15f747bb3e5238b4005b35b", 216 | "name": "Charles Koga", 217 | "email_address": "charles@honchodesign.com", 218 | "personable_type": "User", 219 | "title": "Principal Solutions Technician", 220 | "bio": null, 221 | "location": null, 222 | "created_at": "2022-11-22T08:23:22.066Z", 223 | "updated_at": "2022-11-22T08:23:22.066Z", 224 | "admin": false, 225 | "owner": false, 226 | "client": false, 227 | "employee": false, 228 | "time_zone": "Etc/UTC", 229 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBNdkkT4=--6b5d8dd66434670c75d33036ca0fb8e13fa7be94/avatar?v=1", 230 | "can_manage_projects": true, 231 | "can_manage_people": true 232 | } 233 | ``` 234 | 235 | ###### Copy as cURL 236 | 237 | ``` shell 238 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/people/2.json 239 | ``` 240 | 241 | 242 | Get my personal info 243 | -------------------- 244 | 245 | * `GET /my/profile.json` will return the current user's personal info. 246 | 247 | See the [Get person](#get-person) endpoint for an example of the JSON response. 248 | 249 | ###### Copy as cURL 250 | 251 | ``` shell 252 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/my/profile.json 253 | ``` 254 | -------------------------------------------------------------------------------- /sections/question_answers.md: -------------------------------------------------------------------------------- 1 | Question answers 2 | ================ 3 | 4 | Endpoints: 5 | 6 | - [Get question answers](#get-question-answers) 7 | - [Get a question answer](#get-a-question-answer) 8 | 9 | Get question answers 10 | -------------------- 11 | 12 | * `GET /buckets/1/questions/2/answers.json` will return a [paginated list][pagination] of answers in the project with an ID of `1` and the question with ID of `2`. 13 | 14 | ###### Example JSON Response 15 | 16 | ```json 17 | [ 18 | { 19 | "id": 1069479547, 20 | "status": "active", 21 | "visible_to_clients": false, 22 | "created_at": "2022-11-22T12:05:58.169Z", 23 | "updated_at": "2022-11-22T12:05:58.169Z", 24 | "title": "Answer to “What did you work on today?”", 25 | "inherits_status": true, 26 | "type": "Question::Answer", 27 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/question_answers/1069479547.json", 28 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/question_answers/1069479547", 29 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5NTQ3P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--d845e9d18c423a5f3d1d84039d37c670ba8b0066.json", 30 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479547/subscription.json", 31 | "comments_count": 0, 32 | "comments_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479547/comments.json", 33 | "parent": { 34 | "id": 1069479362, 35 | "title": "What did you work on today?", 36 | "type": "Question", 37 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/questions/1069479362.json", 38 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/questions/1069479362" 39 | }, 40 | "bucket": { 41 | "id": 2085958499, 42 | "name": "The Leto Laptop", 43 | "type": "Project" 44 | }, 45 | "creator": { 46 | "id": 1049715915, 47 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--aeb392ebf54ffd820e45f27add22bae3a8c7da56", 48 | "name": "Annie Bryan", 49 | "email_address": "annie@honchodesign.com", 50 | "personable_type": "User", 51 | "title": "Central Markets Manager", 52 | "bio": "To open a store is easy, to keep it open is an art", 53 | "location": null, 54 | "created_at": "2022-11-22T08:23:21.911Z", 55 | "updated_at": "2022-11-22T08:23:21.911Z", 56 | "admin": false, 57 | "owner": false, 58 | "client": false, 59 | "employee": true, 60 | "time_zone": "America/Chicago", 61 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMtkkT4=--9927c47a4cbee30a7f9aea667882496aba799149/avatar?v=1", 62 | "company": { 63 | "id": 1033447817, 64 | "name": "Honcho Design" 65 | }, 66 | "can_manage_projects": true, 67 | "can_manage_people": true 68 | }, 69 | "content": "
Last week or so was tough, but I think we're back on track. The next design presentation is coming up and we're in good shape.
", 70 | "group_on": "2022-11-22" 71 | } 72 | ] 73 | ``` 74 | 75 | ###### Copy as cURL 76 | 77 | ``` shell 78 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/questions/2/answers.json 79 | ``` 80 | 81 | Get a question answer 82 | --------------------- 83 | 84 | * `GET /buckets/1/question_answers/2.json` will return the answer with an ID of `2` in the project with an ID of `1`. 85 | 86 | ###### Example JSON Response 87 | 88 | ```json 89 | { 90 | "id": 1069479547, 91 | "status": "active", 92 | "visible_to_clients": false, 93 | "created_at": "2022-11-22T12:05:58.169Z", 94 | "updated_at": "2022-11-22T12:05:58.169Z", 95 | "title": "Answer to “What did you work on today?”", 96 | "inherits_status": true, 97 | "type": "Question::Answer", 98 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/question_answers/1069479547.json", 99 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/question_answers/1069479547", 100 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5NTQ3P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--d845e9d18c423a5f3d1d84039d37c670ba8b0066.json", 101 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479547/subscription.json", 102 | "comments_count": 0, 103 | "comments_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479547/comments.json", 104 | "parent": { 105 | "id": 1069479362, 106 | "title": "What did you work on today?", 107 | "type": "Question", 108 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/questions/1069479362.json", 109 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/questions/1069479362" 110 | }, 111 | "bucket": { 112 | "id": 2085958499, 113 | "name": "The Leto Laptop", 114 | "type": "Project" 115 | }, 116 | "creator": { 117 | "id": 1049715915, 118 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--aeb392ebf54ffd820e45f27add22bae3a8c7da56", 119 | "name": "Annie Bryan", 120 | "email_address": "annie@honchodesign.com", 121 | "personable_type": "User", 122 | "title": "Central Markets Manager", 123 | "bio": "To open a store is easy, to keep it open is an art", 124 | "location": null, 125 | "created_at": "2022-11-22T08:23:21.911Z", 126 | "updated_at": "2022-11-22T08:23:21.911Z", 127 | "admin": false, 128 | "owner": false, 129 | "client": false, 130 | "employee": true, 131 | "time_zone": "America/Chicago", 132 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMtkkT4=--9927c47a4cbee30a7f9aea667882496aba799149/avatar?v=1", 133 | "company": { 134 | "id": 1033447817, 135 | "name": "Honcho Design" 136 | }, 137 | "can_manage_projects": true, 138 | "can_manage_people": true 139 | }, 140 | "content": "
Last week or so was tough, but I think we're back on track. The next design presentation is coming up and we're in good shape.
", 141 | "group_on": "2022-11-22" 142 | } 143 | ``` 144 | 145 | ###### Copy as cURL 146 | 147 | ``` shell 148 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/question_answers/2.json 149 | ``` 150 | 151 | [pagination]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination 152 | -------------------------------------------------------------------------------- /sections/questionnaires.md: -------------------------------------------------------------------------------- 1 | Questionnaires 2 | ============== 3 | 4 | All automatic check-ins questions under a project are children of a questionnaire resource. 5 | 6 | Endpoints: 7 | 8 | - [Get questionnaire](#get-questionnaire) 9 | 10 | Get questionnaire 11 | ----------------- 12 | 13 | * `GET /buckets/1/questionnaires/2.json` will return the questionnaire for the project with an ID of `1`. 14 | 15 | To get the questionnaire ID for a project, see the [Get a Project][project] endpoint's `dock` payload. To retrieve its questions, see the [Get questions][questions] endpoint. 16 | 17 | ###### Example JSON Response 18 | 19 | ```json 20 | { 21 | "id": 1069479343, 22 | "status": "active", 23 | "visible_to_clients": false, 24 | "created_at": "2022-11-22T08:23:58.246Z", 25 | "updated_at": "2022-11-22T08:25:12.647Z", 26 | "title": "Automatic Check-ins", 27 | "inherits_status": true, 28 | "type": "Questionnaire", 29 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/questionnaires/1069479343.json", 30 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/questionnaires/1069479343", 31 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5MzQzP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--6954f9a736e1acaa2632328b7ff8a9bcda0b1a10.json", 32 | "bucket": { 33 | "id": 2085958499, 34 | "name": "The Leto Laptop", 35 | "type": "Project" 36 | }, 37 | "creator": { 38 | "id": 1049715914, 39 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 40 | "name": "Victor Cooper", 41 | "email_address": "victor@honchodesign.com", 42 | "personable_type": "User", 43 | "title": "Chief Strategist", 44 | "bio": "Don’t let your dreams be dreams", 45 | "location": "Chicago, IL", 46 | "created_at": "2022-11-22T08:23:21.732Z", 47 | "updated_at": "2022-11-22T08:23:21.904Z", 48 | "admin": true, 49 | "owner": true, 50 | "client": false, 51 | "employee": true, 52 | "time_zone": "America/Chicago", 53 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 54 | "company": { 55 | "id": 1033447817, 56 | "name": "Honcho Design" 57 | }, 58 | "can_manage_projects": true, 59 | "can_manage_people": true 60 | }, 61 | "name": "Automatic Check-ins", 62 | "questions_count": 1, 63 | "questions_url": "https://3.basecampapi.com/195539477/buckets/2085958499/questionnaires/1069479343/questions.json" 64 | } 65 | ``` 66 | 67 | 68 | ###### Copy as cURL 69 | 70 | ``` shell 71 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/questionnaires/2.json 72 | ``` 73 | 74 | [project]: https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#get-a-project 75 | [questions]: https://github.com/basecamp/bc3-api/blob/master/sections/questions.md#get-questions 76 | -------------------------------------------------------------------------------- /sections/questions.md: -------------------------------------------------------------------------------- 1 | Questions 2 | ========= 3 | 4 | Endpoints: 5 | 6 | - [Get questions](#get-questions) 7 | - [Get a question](#get-a-question) 8 | 9 | Get questions 10 | ------------- 11 | 12 | * `GET /buckets/1/questionnaires/2/questions.json` will return a [paginated list][pagination] of questions in the project with an ID of `1` and the questionnaire with ID of `2`. 13 | 14 | ###### Example JSON Response 15 | 16 | ```json 17 | [ 18 | { 19 | "id": 1069479362, 20 | "status": "active", 21 | "visible_to_clients": false, 22 | "created_at": "2022-10-29T10:56:58.169Z", 23 | "updated_at": "2022-11-22T08:25:12.645Z", 24 | "title": "What did you work on today?", 25 | "inherits_status": true, 26 | "type": "Question", 27 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/questions/1069479362.json", 28 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/questions/1069479362", 29 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5MzYyP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--98a22f48366f2b97eda3cc5996bcbd018f2118e3.json", 30 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479362/subscription.json", 31 | "parent": { 32 | "id": 1069479343, 33 | "title": "Automatic Check-ins", 34 | "type": "Questionnaire", 35 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/questionnaires/1069479343.json", 36 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/questionnaires/1069479343" 37 | }, 38 | "bucket": { 39 | "id": 2085958499, 40 | "name": "The Leto Laptop", 41 | "type": "Project" 42 | }, 43 | "creator": { 44 | "id": 1049715914, 45 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 46 | "name": "Victor Cooper", 47 | "email_address": "victor@honchodesign.com", 48 | "personable_type": "User", 49 | "title": "Chief Strategist", 50 | "bio": "Don’t let your dreams be dreams", 51 | "location": "Chicago, IL", 52 | "created_at": "2022-11-22T08:23:21.732Z", 53 | "updated_at": "2022-11-22T08:23:21.904Z", 54 | "admin": true, 55 | "owner": true, 56 | "client": false, 57 | "employee": true, 58 | "time_zone": "America/Chicago", 59 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 60 | "company": { 61 | "id": 1033447817, 62 | "name": "Honcho Design" 63 | }, 64 | "can_manage_projects": true, 65 | "can_manage_people": true 66 | }, 67 | "paused": false, 68 | "schedule": { 69 | "frequency": "every_day", 70 | "days": [ 71 | 1, 72 | 2, 73 | 3, 74 | 4, 75 | 5 76 | ], 77 | "hour": 17, 78 | "minute": 0, 79 | "week_instance": null, 80 | "week_interval": null, 81 | "month_interval": null, 82 | "start_date": "2022-11-22", 83 | "end_date": null 84 | }, 85 | "answers_count": 32, 86 | "answers_url": "https://3.basecampapi.com/195539477/buckets/2085958499/questions/1069479362/answers.json" 87 | } 88 | ] 89 | ``` 90 | 91 | ###### Copy as cURL 92 | 93 | ``` shell 94 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/questionnaires/2/questions.json 95 | ``` 96 | 97 | Get a question 98 | -------------- 99 | 100 | * `GET /buckets/1/questions/2.json` will return the question with an ID of `2` in the project with an ID of `1`. 101 | 102 | ###### Example JSON Response 103 | 104 | ```json 105 | { 106 | "id": 1069479362, 107 | "status": "active", 108 | "visible_to_clients": false, 109 | "created_at": "2022-10-29T10:56:58.169Z", 110 | "updated_at": "2022-11-22T08:25:12.645Z", 111 | "title": "What did you work on today?", 112 | "inherits_status": true, 113 | "type": "Question", 114 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/questions/1069479362.json", 115 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/questions/1069479362", 116 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5MzYyP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--98a22f48366f2b97eda3cc5996bcbd018f2118e3.json", 117 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479362/subscription.json", 118 | "parent": { 119 | "id": 1069479343, 120 | "title": "Automatic Check-ins", 121 | "type": "Questionnaire", 122 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/questionnaires/1069479343.json", 123 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/questionnaires/1069479343" 124 | }, 125 | "bucket": { 126 | "id": 2085958499, 127 | "name": "The Leto Laptop", 128 | "type": "Project" 129 | }, 130 | "creator": { 131 | "id": 1049715914, 132 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 133 | "name": "Victor Cooper", 134 | "email_address": "victor@honchodesign.com", 135 | "personable_type": "User", 136 | "title": "Chief Strategist", 137 | "bio": "Don’t let your dreams be dreams", 138 | "location": "Chicago, IL", 139 | "created_at": "2022-11-22T08:23:21.732Z", 140 | "updated_at": "2022-11-22T08:23:21.904Z", 141 | "admin": true, 142 | "owner": true, 143 | "client": false, 144 | "employee": true, 145 | "time_zone": "America/Chicago", 146 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 147 | "company": { 148 | "id": 1033447817, 149 | "name": "Honcho Design" 150 | }, 151 | "can_manage_projects": true, 152 | "can_manage_people": true 153 | }, 154 | "paused": false, 155 | "schedule": { 156 | "frequency": "every_day", 157 | "days": [ 158 | 1, 159 | 2, 160 | 3, 161 | 4, 162 | 5 163 | ], 164 | "hour": 17, 165 | "minute": 0, 166 | "week_instance": null, 167 | "week_interval": null, 168 | "month_interval": null, 169 | "start_date": "2022-11-22", 170 | "end_date": null 171 | }, 172 | "answers_count": 32, 173 | "answers_url": "https://3.basecampapi.com/195539477/buckets/2085958499/questions/1069479362/answers.json" 174 | } 175 | ``` 176 | 177 | ###### Copy as cURL 178 | 179 | ``` shell 180 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/questions/2.json 181 | ``` 182 | 183 | [pagination]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination 184 | -------------------------------------------------------------------------------- /sections/recordings.md: -------------------------------------------------------------------------------- 1 | Recordings 2 | ========== 3 | 4 | Most of the data structures in the Basecamp 4 API are represented as "Recordings", with generic actions available to be performed. 5 | 6 | Endpoints: 7 | 8 | - [Get recordings](#get-recordings) 9 | - [Trash a recording](#trash-a-recording) 10 | - [Archive a recording](#archive-a-recording) 11 | - [Unarchive a recording](#unarchive-a-recording) 12 | 13 | Get recordings 14 | -------------- 15 | 16 | * `GET /projects/recordings.json` will return a [paginated list][1] of records for the given `type` of recording. 17 | 18 | **Required parameters**: `type`, which must be `Comment`, `Document`, `Message`, `Question::Answer`, `Schedule::Entry`, `Todo`, `Todolist`, `Upload`, or `Vault`). 19 | 20 | _Optional parameters_: 21 | 22 | * `bucket` - Single or comma separated list of [project][2] IDs. Default: All active projects visible to the current user. 23 | * `status` - Options: `active`, `archived`, or `trashed`. Default: `active` 24 | * `sort` - Options: `created_at` or `updated_at`. Default: `created_at`. 25 | * `direction` - Options: `desc` or `asc`. Default: `desc`. 26 | 27 | Examples: `/projects/recordings.json?type=Todo`, `/projects/recordings.json?type=Message&bucket=1`, `/projects/recordings.json?type=Document&bucket=1,2&sort=updated_at&direction=asc` 28 | 29 | 30 | Trash a recording 31 | ----------------- 32 | 33 | * `PUT /buckets/1/recordings/2/status/trashed.json` will mark the recording with an ID of `2`in the project with ID `1` as trashed. 34 | 35 | No parameters required. Returns `204 No Content` if successful. 36 | 37 | ###### Copy as cURL 38 | 39 | ``` shell 40 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT \ 41 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/recordings/2/status/trashed.json 42 | ``` 43 | 44 | 45 | Archive a recording 46 | ------------------- 47 | 48 | * `PUT /buckets/1/recordings/2/status/archived.json` will mark the recording with an ID of `2`in the project with ID `1` as archived. 49 | 50 | No parameters required. Returns `204 No Content` if successful. 51 | 52 | ###### Copy as cURL 53 | 54 | ``` shell 55 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT \ 56 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/recordings/2/status/archived.json 57 | ``` 58 | 59 | 60 | Unarchive a recording 61 | --------------------- 62 | 63 | * `PUT /buckets/1/recordings/2/status/active.json` will mark the recording with an ID of `2`in the project with ID `1` as active. 64 | 65 | No parameters required. Returns `204 No Content` if successful. 66 | 67 | ###### Copy as cURL 68 | 69 | ``` shell 70 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT \ 71 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/recordings/2/status/active.json 72 | ``` 73 | 74 | [1]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination 75 | [2]: https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#projects 76 | -------------------------------------------------------------------------------- /sections/rich_text.md: -------------------------------------------------------------------------------- 1 | Rich text 2 | ========= 3 | 4 | Many resources, including messages, documents, and comments, represent their content as rich text in HTML. Rich text content may contain lists, block quotes, simple formatting, and inline attachments such as mentions, images, and files. 5 | 6 | 7 | Working with rich text HTML 8 | --------------------------- 9 | 10 | If your application reads Basecamp rich text content, it must be able to process HTML. Use a web view component to render rich text content unmodified. Or, if your application needs a plain-text representation of rich text content, first decode any HTML entities, then replace `
` tags with line breaks, and finally strip the remaining HTML tags. 11 | 12 | Similarly, if your application writes rich text content, it must be able to generate well-formed HTML. At a minimum, this means properly encoding HTML entities and replacing line breaks with `
` tags. 13 | 14 | Applications that modify existing rich text content should take special care not to discard any formatting or attachments during processing. Consider using a full HTML parser to manipulate rich text content. Libraries such as [Nokogiri](http://www.nokogiri.org) (Ruby) and [Cheerio](https://github.com/cheeriojs/cheerio) (Node.js) are good fits for this scenario. 15 | 16 | 17 | Allowed HTML tags 18 | ----------------- 19 | 20 | You may use the following standard HTML tags in rich text content: `div`, `h1`, `br`, `strong`, `em`, `strike`, `a` (with an `href` attribute), `pre`, `ol`, `ul`, `li`, and `blockquote`. Any other tags will be removed automatically. 21 | 22 | The special `` tag allows you to insert an inline attachment. Each `` has an `sgid` attribute which points to the `attachable_sgid` attribute of an attachable Basecamp resource. Your application will receive a rendered representation of the attachable resource inside the `` tag in API responses. 23 | 24 | 25 | Inserting a mention 26 | ------------------- 27 | 28 | Mentions in rich text content are attachments that reference a [Person](people.md) on the current [Project](projects.md). When you submit rich text content with mentions, Basecamp delivers a special notification to each mentioned person. 29 | 30 | Create a mention in Basecamp's rich text editor by typing "@" and selecting a person from the drop-down list. Create mentions with the API by inserting a `` tag with an `sgid` attribute pointing to the person's `attachable_sgid`. 31 | 32 | For example, to mention this person: 33 | 34 | ```json 35 | { 36 | "id": 1007299208, 37 | "name": "Victor Cooper", 38 | "attachable_sgid": "BAh7CEkiCG..." 39 | } 40 | ``` 41 | 42 | Submit this rich text content: 43 | 44 | ```html 45 | 46 | ``` 47 | 48 | The Basecamp API will return an expanded representation similar to the following: 49 | 50 | ```html 51 | 52 |
53 | 54 |
Victor
55 |
56 | 57 | ``` 58 | 59 | 60 | Inserting an image or file attachment 61 | ------------------------------------- 62 | 63 | To insert an image or file attachment in rich text content, first [create an Attachment](attachments.md#create-an-attachment). You will receive an `attachable_sgid` in response: 64 | 65 | ```json 66 | { 67 | "attachable_sgid": "BAh7CEkiCG..." 68 | } 69 | ```` 70 | 71 | Take this `attachable_sgid` and use it to submit rich text content with a `` tag: 72 | 73 | ```html 74 | 75 | ``` 76 | 77 | If the attachment is an image, you may optionally include a `caption` attribute, which will appear below the attachment in rendered rich text content: 78 | 79 | ```html 80 | 81 | ``` 82 | 83 | The Basecamp API will return an expanded representation similar to the following: 84 | 85 | ```html 86 | 87 |
88 | 89 |
My photo
90 |
91 | 92 | ``` 93 | 94 | Be sure to provide an appropriate `Content-Type` header when creating image attachments. If the attachment's content type does not start with `image/`, it will be presented as a file instead of an image with a preview. 95 | 96 | Also, notice that you must create new attachments for rich text contents, you can't reuse them from other elements (e.g: uploads). 97 | 98 | ### Image galleries 99 | You can also present image attachments grouped in a _gallery_. For this, you need to include the `presentation="gallery"` attribute to the `bc-attachment` element and they need to be inside their own container element, typically a `
`. That is: 100 | ``` 101 |
102 | 103 | 104 |
105 | ``` 106 | 107 | Appendix 108 | -------- 109 | 110 | ### Rich text content attributes 111 | 112 | The following attributes contain rich text content in HTML format: 113 | 114 | - [Comment `content`](comments.md#get-a-comment) 115 | - [Client approval `content`](client_approvals.md#get-a-client-approval) 116 | - [Client correspondence `content`](client_correspondences.md#get-a-client-correspondence) 117 | - [Client reply `content`](client_replies.md#get-a-client-reply) 118 | - [Document `content`](documents.md#get-a-document) 119 | - [Message `content`](messages.md#get-a-message) 120 | - [Question answer `content`](question_answers.md#get-a-question-answer) 121 | - [Schedule entry `description`](schedule_entries.md#get-a-schedule-entry) 122 | - [To-do list `description`](todolists.md#get-a-to-do-list) 123 | - [To-do `description`](todos.md#get-a-to-do) 124 | - [Upload `description`](uploads.md#get-an-upload) 125 | 126 | 127 | ### Attachable resources 128 | 129 | The following resources contain an `attachable_sgid` attribute which can be used to create a `` tag in rich text content: 130 | 131 | - [Attachment](attachments.md) 132 | - [Person](people.md) 133 | -------------------------------------------------------------------------------- /sections/schedule_entries.md: -------------------------------------------------------------------------------- 1 | Schedule entries 2 | ================ 3 | 4 | Endpoints: 5 | 6 | - [Get schedule entries](#get-schedule-entries) 7 | - [Get a schedule entry](#get-a-schedule-entry) 8 | - [Create a schedule entry](#create-a-schedule-entry) 9 | - [Update a schedule entry](#update-a-schedule-entry) 10 | - [Trash a schedule entry][trash] 11 | 12 | Get schedule entries 13 | -------------------- 14 | 15 | * `GET /buckets/1/schedules/3/entries.json` will return a [paginated list][pagination] of active schedule entries in the project with an ID of `1` and the schedule with ID of `3`. 16 | 17 | To get the schedule ID for a project, see the [Get schedule][schedule] endpoint. 18 | 19 | _Optional query parameters_: 20 | 21 | * `status` - when set to `archived` or `trashed`, will return archived or trashed schedule entries that are in this schedule. 22 | 23 | ###### Example JSON Response 24 | 25 | ```json 26 | [ 27 | { 28 | "id": 1069479847, 29 | "status": "active", 30 | "visible_to_clients": false, 31 | "created_at": "2022-11-22T08:25:04.190Z", 32 | "updated_at": "2022-11-22T08:25:04.316Z", 33 | "title": "Team Meeting", 34 | "inherits_status": true, 35 | "type": "Schedule::Entry", 36 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/schedule_entries/1069479847.json", 37 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/schedule_entries/1069479847", 38 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5ODQ3P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--1c0cc0c23c279ac645718b2ea9912d5513075d97.json", 39 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479847/subscription.json", 40 | "comments_count": 0, 41 | "comments_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479847/comments.json", 42 | "parent": { 43 | "id": 1069479342, 44 | "title": "Schedule", 45 | "type": "Schedule", 46 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/schedules/1069479342.json", 47 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/schedules/1069479342" 48 | }, 49 | "bucket": { 50 | "id": 2085958499, 51 | "name": "The Leto Laptop", 52 | "type": "Project" 53 | }, 54 | "creator": { 55 | "id": 1049715914, 56 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 57 | "name": "Victor Cooper", 58 | "email_address": "victor@honchodesign.com", 59 | "personable_type": "User", 60 | "title": "Chief Strategist", 61 | "bio": "Don’t let your dreams be dreams", 62 | "location": "Chicago, IL", 63 | "created_at": "2022-11-22T08:23:21.732Z", 64 | "updated_at": "2022-11-22T08:23:21.904Z", 65 | "admin": true, 66 | "owner": true, 67 | "client": false, 68 | "employee": true, 69 | "time_zone": "America/Chicago", 70 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 71 | "company": { 72 | "id": 1033447817, 73 | "name": "Honcho Design" 74 | }, 75 | "can_manage_projects": true, 76 | "can_manage_people": true 77 | }, 78 | "description": "
Time to synergize!
", 79 | "summary": "Team Meeting", 80 | "all_day": false, 81 | "starts_at": "2022-11-23T10:25:04.177Z", 82 | "ends_at": "2022-11-23T14:25:04.177Z", 83 | "participants": [ 84 | { 85 | "id": 1049715921, 86 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTIxP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--61b488a9fa97d2e628aee86cf51a4ba0171888c2", 87 | "name": "Steve Marsh", 88 | "email_address": "steve@honchodesign.com", 89 | "personable_type": "User", 90 | "title": "Legacy Directives Strategist", 91 | "bio": "You can do it!", 92 | "location": null, 93 | "created_at": "2022-11-22T08:23:21.991Z", 94 | "updated_at": "2022-11-22T08:23:21.991Z", 95 | "admin": false, 96 | "owner": false, 97 | "client": false, 98 | "employee": true, 99 | "time_zone": "Etc/UTC", 100 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBNFkkT4=--c57bba9b44447be39d4a79a5e7f2a592cae9e82c/avatar?v=1", 101 | "company": { 102 | "id": 1033447817, 103 | "name": "Honcho Design" 104 | }, 105 | "can_manage_projects": true, 106 | "can_manage_people": true 107 | } 108 | ] 109 | } 110 | ] 111 | ``` 112 | 113 | ###### Copy as cURL 114 | 115 | ``` shell 116 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/schedules/3/entries.json 117 | ``` 118 | 119 | 120 | Get a schedule entry 121 | -------------------- 122 | 123 | * `GET /buckets/1/schedule_entries/2.json` will return the schedule entry with an ID of `2` in the project with an ID of `1`. 124 | 125 | **Note:** this endpoint redirects to the first individual occurrence of the entry, for **recurring schedule entries**. It's also possible to access a recurring schedule entry via any of the individual occurrences: `GET /buckets/1/schedule_entries/2/occurrences/20190218.json` will return the occurrence for a recurring schedule entry with an ID of `2`, happening on `2019-02-18`, in the project with an ID of `1`. It'll return 404 for invalid occurrences. 126 | 127 | ###### Example JSON Response 128 | 129 | ```json 130 | { 131 | "id": 1069479847, 132 | "status": "active", 133 | "visible_to_clients": false, 134 | "created_at": "2022-11-22T08:25:04.190Z", 135 | "updated_at": "2022-11-22T08:25:04.316Z", 136 | "title": "Team Meeting", 137 | "inherits_status": true, 138 | "type": "Schedule::Entry", 139 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/schedule_entries/1069479847.json", 140 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/schedule_entries/1069479847", 141 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5ODQ3P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--1c0cc0c23c279ac645718b2ea9912d5513075d97.json", 142 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479847/subscription.json", 143 | "comments_count": 0, 144 | "comments_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479847/comments.json", 145 | "parent": { 146 | "id": 1069479342, 147 | "title": "Schedule", 148 | "type": "Schedule", 149 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/schedules/1069479342.json", 150 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/schedules/1069479342" 151 | }, 152 | "bucket": { 153 | "id": 2085958499, 154 | "name": "The Leto Laptop", 155 | "type": "Project" 156 | }, 157 | "creator": { 158 | "id": 1049715914, 159 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 160 | "name": "Victor Cooper", 161 | "email_address": "victor@honchodesign.com", 162 | "personable_type": "User", 163 | "title": "Chief Strategist", 164 | "bio": "Don’t let your dreams be dreams", 165 | "location": "Chicago, IL", 166 | "created_at": "2022-11-22T08:23:21.732Z", 167 | "updated_at": "2022-11-22T08:23:21.904Z", 168 | "admin": true, 169 | "owner": true, 170 | "client": false, 171 | "employee": true, 172 | "time_zone": "America/Chicago", 173 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 174 | "company": { 175 | "id": 1033447817, 176 | "name": "Honcho Design" 177 | }, 178 | "can_manage_projects": true, 179 | "can_manage_people": true 180 | }, 181 | "description": "
Time to synergize!
", 182 | "summary": "Team Meeting", 183 | "all_day": false, 184 | "starts_at": "2022-11-23T10:25:04.177Z", 185 | "ends_at": "2022-11-23T14:25:04.177Z", 186 | "participants": [ 187 | { 188 | "id": 1049715921, 189 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTIxP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--61b488a9fa97d2e628aee86cf51a4ba0171888c2", 190 | "name": "Steve Marsh", 191 | "email_address": "steve@honchodesign.com", 192 | "personable_type": "User", 193 | "title": "Legacy Directives Strategist", 194 | "bio": "You can do it!", 195 | "location": null, 196 | "created_at": "2022-11-22T08:23:21.991Z", 197 | "updated_at": "2022-11-22T08:23:21.991Z", 198 | "admin": false, 199 | "owner": false, 200 | "client": false, 201 | "employee": true, 202 | "time_zone": "Etc/UTC", 203 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBNFkkT4=--c57bba9b44447be39d4a79a5e7f2a592cae9e82c/avatar?v=1", 204 | "company": { 205 | "id": 1033447817, 206 | "name": "Honcho Design" 207 | }, 208 | "can_manage_projects": true, 209 | "can_manage_people": true 210 | } 211 | ] 212 | } 213 | ``` 214 | 215 | 216 | Recurring schedule entries will include an additional `recurrence_schedule` attribute. For example: 217 | 218 | ```json 219 | "recurrence_schedule": { 220 | "frequency": "every_month", 221 | "days": [ 222 | 1 223 | ], 224 | "hour": 10, 225 | "minute": 30, 226 | "week_instance": 3, 227 | "start_date": "2019-02-18", 228 | "end_date": "2019-10-25" 229 | } 230 | ``` 231 | 232 | ###### Copy as cURL 233 | 234 | ``` shell 235 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/schedule_entries/2.json 236 | ``` 237 | 238 | 239 | Create a schedule entry 240 | ----------------------- 241 | 242 | * `POST /buckets/1/schedules/3/entries.json` creates a schedule entry in the project with ID `1` and under the schedule with an ID of `3`. 243 | 244 | **Required parameters**: 245 | 246 | * `summary` - what this schedule entry is about 247 | * `starts_at` - date-time (ISO 8601) for when this schedule entry begins 248 | * `ends_at` - date-time (ISO 8601) for when this schedule entry ends 249 | 250 | _Optional parameters_: 251 | 252 | * `description` - containing more information about the schedule entry. See our [Rich text guide][rich] for what HTML tags allowed. 253 | * `participant_ids` - an array of people IDs that will participate in this entry. Please see the [Get people][people] endpoints to retrieve them. 254 | * `all_day` - when set to `true`, the schedule entry will not have a specific start or end time, and instead will be held for the entire day or days denoted in `starts_at` and `ends_at` 255 | * `notify` - when set to `true`, will notify the participants about the entry 256 | 257 | This endpoint will return `201 Created` with the current JSON representation of the schedule entry if the creation was a success. See the [Get a schedule entry](#get-a-schedule-entry) endpoint for more info on the payload. 258 | 259 | ###### Example JSON Request 260 | 261 | ``` json 262 | { 263 | "summary": "Important Meeting", 264 | "starts_at": "2015-06-04T00:00:00Z", 265 | "ends_at": "2015-06-04T02:00:00Z" 266 | } 267 | ``` 268 | 269 | ###### Copy as cURL 270 | 271 | ``` shell 272 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 273 | -d '{"summary":"Important Meeting","starts_at":"2015-06-04T00:00:00Z","ends_at":"2015-06-04T00:00:00Z"}' \ 274 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/schedules/3/entries.json 275 | ``` 276 | 277 | 278 | Update a schedule entry 279 | ----------------------- 280 | 281 | * `PUT /buckets/1/schedule_entries/2.json` allows changing of the schedule entry with an ID of `2` in the project with ID `1`. 282 | 283 | Clients may change any of the required or optional parameters as listed in the [Create a schedule entry](#create-a-schedule-entry) endpoint. 284 | 285 | This endpoint will return `200 OK` with the current JSON representation of the schedule entry if the update was a success. See the [Get a schedule entry](#get-a-schedule-entry) endpoint for more info on the payload. 286 | 287 | ###### Example JSON Request 288 | 289 | ``` json 290 | { 291 | "summary": "All Day Meeting", 292 | "starts_at": "2015-06-04", 293 | "ends_at": "2015-06-04", 294 | "all_day": true 295 | } 296 | ``` 297 | 298 | ###### Copy as cURL 299 | 300 | ``` shell 301 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 302 | -d '{"summary":"All Day Meeting","starts_at":"2015-06-04","ends_at":"2015-06-04","all_day":true}' -X PUT \ 303 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/schedule_entries/2.json 304 | ``` 305 | 306 | 307 | [trash]: https://github.com/basecamp/bc3-api/blob/master/sections/recordings.md#trash-a-recording 308 | [pagination]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination 309 | [schedule]: https://github.com/basecamp/bc3-api/blob/master/sections/schedules.md#get-schedule 310 | [rich]: https://github.com/basecamp/bc3-api/blob/master/sections/rich_text.md 311 | [people]: https://github.com/basecamp/bc3-api/blob/master/sections/people.md#people 312 | -------------------------------------------------------------------------------- /sections/schedules.md: -------------------------------------------------------------------------------- 1 | Schedules 2 | ========= 3 | 4 | All schedule entries under a project are children of a schedule resource. 5 | 6 | Endpoints: 7 | 8 | - [Get schedule](#get-schedule) 9 | - [Update a schedule](#update-a-schedule) 10 | 11 | 12 | Get schedule 13 | ------------ 14 | 15 | * `GET /buckets/1/schedules/2.json` will return the schedule for the project with an ID of `1`. 16 | 17 | To get the schedule ID for a project, see the [Get a project][1] endpoint's `dock` payload. To retrieve its schedule entries lists, see the [Get schedule entries][2] endpoint. 18 | 19 | ###### Example JSON Response 20 | 21 | ```json 22 | { 23 | "id": 1069479342, 24 | "status": "active", 25 | "visible_to_clients": false, 26 | "created_at": "2022-11-22T08:23:58.237Z", 27 | "updated_at": "2022-11-22T08:25:04.318Z", 28 | "title": "Schedule", 29 | "inherits_status": true, 30 | "type": "Schedule", 31 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/schedules/1069479342.json", 32 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/schedules/1069479342", 33 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5MzQyP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--c25a35abffcd11650599ed79c2b7aa7b62c72a60.json", 34 | "position": 5, 35 | "bucket": { 36 | "id": 2085958499, 37 | "name": "The Leto Laptop", 38 | "type": "Project" 39 | }, 40 | "creator": { 41 | "id": 1049715914, 42 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 43 | "name": "Victor Cooper", 44 | "email_address": "victor@honchodesign.com", 45 | "personable_type": "User", 46 | "title": "Chief Strategist", 47 | "bio": "Don’t let your dreams be dreams", 48 | "location": "Chicago, IL", 49 | "created_at": "2022-11-22T08:23:21.732Z", 50 | "updated_at": "2022-11-22T08:23:21.904Z", 51 | "admin": true, 52 | "owner": true, 53 | "client": false, 54 | "employee": true, 55 | "time_zone": "America/Chicago", 56 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 57 | "company": { 58 | "id": 1033447817, 59 | "name": "Honcho Design" 60 | }, 61 | "can_manage_projects": true, 62 | "can_manage_people": true 63 | }, 64 | "include_due_assignments": true, 65 | "entries_count": 1, 66 | "entries_url": "https://3.basecampapi.com/195539477/buckets/2085958499/schedules/1069479342/entries.json" 67 | } 68 | ``` 69 | 70 | ###### Copy as cURL 71 | 72 | ``` shell 73 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/schedules/2.json 74 | ``` 75 | 76 | Update a schedule 77 | ----------------------- 78 | 79 | * `PUT /buckets/1/schedules/2.json` allows changing of the schedule with an ID of `2` in the project with ID `1`. 80 | 81 | **Required parameters**: 82 | 83 | * `include_due_assignments` - whether the schedule should include due dates from to-dos, cards and steps. 84 | 85 | This endpoint will return `200 OK` with the current JSON representation of the schedule if the update was a success. 86 | 87 | ###### Example JSON Request 88 | 89 | ``` json 90 | { 91 | "include_due_assignments": "false" 92 | } 93 | ``` 94 | 95 | ###### Copy as cURL 96 | 97 | ``` shell 98 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 99 | -d '{"schedule": {"include_due_assignments": "false"}}' -X PUT \ 100 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/schedules/2.json 101 | ``` 102 | 103 | 104 | [1]: https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#get-a-project 105 | [2]: https://github.com/basecamp/bc3-api/blob/master/sections/schedule_entries.md#get-schedule-entries 106 | [3]: https://github.com/basecamp/bc3-api/blob/master/sections/recordings.md#trash-a-recording 107 | -------------------------------------------------------------------------------- /sections/subscriptions.md: -------------------------------------------------------------------------------- 1 | Subscriptions 2 | ============= 3 | 4 | Many of the resources in Basecamp 4 that can be commented on have _subscribers_, that is, people that will get notified when a new comment is added. To know if it's possible to modify the subscriptions for a recording, check its JSON response for the `subscription_url` attribute. This attribute contains the URL to hit to get information about current subscribers and to add/remove subscribers. 5 | 6 | Endpoints: 7 | 8 | - [Get subscription](#get-subscription) 9 | - [Subscribe current user](#subscribe-current-user) 10 | - [Unsubscribe current user](#unsubscribe-current-user) 11 | - [Update subscription](#update-subscription) 12 | 13 | 14 | Get subscription 15 | ---------------- 16 | 17 | * `GET /buckets/1/recordings/2/subscription.json` will return subscription information for a recording with an ID of `2` in the bucket with ID `1`. 18 | 19 | ###### Example JSON Response 20 | 21 | ```json 22 | { 23 | "subscribed": true, 24 | "count": 2, 25 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479351/subscription.json", 26 | "subscribers": [ 27 | { 28 | "id": 1049715914, 29 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 30 | "name": "Victor Cooper", 31 | "email_address": "victor@honchodesign.com", 32 | "personable_type": "User", 33 | "title": "Chief Strategist", 34 | "bio": "Don’t let your dreams be dreams", 35 | "location": "Chicago, IL", 36 | "created_at": "2022-11-22T08:23:21.732Z", 37 | "updated_at": "2022-11-22T08:23:21.904Z", 38 | "admin": true, 39 | "owner": true, 40 | "client": false, 41 | "employee": true, 42 | "time_zone": "America/Chicago", 43 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 44 | "company": { 45 | "id": 1033447817, 46 | "name": "Honcho Design" 47 | }, 48 | "can_manage_projects": true, 49 | "can_manage_people": true 50 | }, 51 | { 52 | "id": 1049715915, 53 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--aeb392ebf54ffd820e45f27add22bae3a8c7da56", 54 | "name": "Annie Bryan", 55 | "email_address": "annie@honchodesign.com", 56 | "personable_type": "User", 57 | "title": "Central Markets Manager", 58 | "bio": "To open a store is easy, to keep it open is an art", 59 | "location": null, 60 | "created_at": "2022-11-22T08:23:21.911Z", 61 | "updated_at": "2022-11-22T08:23:21.911Z", 62 | "admin": false, 63 | "owner": false, 64 | "client": false, 65 | "employee": true, 66 | "time_zone": "America/Chicago", 67 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMtkkT4=--9927c47a4cbee30a7f9aea667882496aba799149/avatar?v=1", 68 | "company": { 69 | "id": 1033447817, 70 | "name": "Honcho Design" 71 | }, 72 | "can_manage_projects": true, 73 | "can_manage_people": true 74 | } 75 | ] 76 | } 77 | ``` 78 | 79 | 80 | ###### Copy as cURL 81 | 82 | ``` shell 83 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/recordings/2/subscription.json 84 | ``` 85 | 86 | Subscribe current user 87 | ---------------------- 88 | 89 | * `POST /buckets/1/recordings/2/subscription.json` will subscribe the current user to the recording with an ID of `2` in the bucket with ID `1`. It returns `200 OK` with the current JSON representation of the recording subscriptions if the creation was a success. See the [Get subscription](#get-subscription) endpoint for an example of such response. 90 | 91 | ###### Copy as cURL 92 | 93 | ``` shell 94 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -X POST \ 95 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/recordings/2/subscription.json 96 | ``` 97 | 98 | Unsubscribe current user 99 | ----------------------- 100 | 101 | * `DELETE /buckets/1/recordings/2/subscription.json` will unsubscribe the current user from the recording with an ID of `2` in the bucket with ID `1`. It returns `204 No Content` in any case, even if the current user wasn't previously subscribed. 102 | 103 | ###### Copy as cURL 104 | 105 | ``` shell 106 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -X DELETE \ 107 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/recordings/2/subscription.json 108 | ``` 109 | 110 | Update subscription 111 | ------------------- 112 | 113 | * `PUT /buckets/1/recordings/2/subscription.json` will add and remove the people given from the list of subscribers for the recording with an ID of `2` in the bucket with ID `1`. It returns `200 OK` with the current JSON representation of the recording subscriptions if the creation was a success. 114 | 115 | **Parameters**: Requests should include at least one of the following parameters. 116 | 117 | * `subscriptions` - an array of people IDs. 118 | * `unsubscriptions` - an array of people IDs. 119 | 120 | ###### Example JSON Request 121 | 122 | ```json 123 | { 124 | "subscriptions": [ 125 | 1049715916 126 | ], 127 | "unsubscriptions": [ 128 | 1049715914 129 | ] 130 | } 131 | ``` 132 | 133 | 134 | 135 | ###### Copy as cURL 136 | 137 | ``` shell 138 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 139 | -d '{"subscriptions":[1049715916], "unsubscriptions":[1049715914]}' -X PUT \ 140 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/recordings/2/subscription.json 141 | ``` 142 | 143 | ###### Example JSON Response 144 | 145 | ```json 146 | { 147 | "subscribed": false, 148 | "count": 2, 149 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479351/subscription.json", 150 | "subscribers": [ 151 | { 152 | "id": 1049715915, 153 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--aeb392ebf54ffd820e45f27add22bae3a8c7da56", 154 | "name": "Annie Bryan", 155 | "email_address": "annie@honchodesign.com", 156 | "personable_type": "User", 157 | "title": "Central Markets Manager", 158 | "bio": "To open a store is easy, to keep it open is an art", 159 | "location": null, 160 | "created_at": "2022-11-22T08:23:21.911Z", 161 | "updated_at": "2022-11-22T08:23:21.911Z", 162 | "admin": false, 163 | "owner": false, 164 | "client": false, 165 | "employee": true, 166 | "time_zone": "America/Chicago", 167 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMtkkT4=--9927c47a4cbee30a7f9aea667882496aba799149/avatar?v=1", 168 | "company": { 169 | "id": 1033447817, 170 | "name": "Honcho Design" 171 | }, 172 | "can_manage_projects": true, 173 | "can_manage_people": true 174 | }, 175 | { 176 | "id": 1049715916, 177 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE2P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--c94599eef0a4237fbaa56ff2648f57f1dae89ffd", 178 | "name": "Cheryl Walters", 179 | "email_address": "cheryl@honchodesign.com", 180 | "personable_type": "User", 181 | "title": "Corporate Integration Director", 182 | "bio": "A joke is a very serious thing", 183 | "location": null, 184 | "created_at": "2022-11-22T08:23:21.926Z", 185 | "updated_at": "2022-11-22T08:23:21.926Z", 186 | "admin": false, 187 | "owner": false, 188 | "client": false, 189 | "employee": true, 190 | "time_zone": "Etc/UTC", 191 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMxkkT4=--0ea74d7e5d39ad2d120da79250b179b7e0b00c44/avatar?v=1", 192 | "company": { 193 | "id": 1033447817, 194 | "name": "Honcho Design" 195 | }, 196 | "can_manage_projects": true, 197 | "can_manage_people": true 198 | } 199 | ] 200 | } 201 | ``` 202 | 203 | -------------------------------------------------------------------------------- /sections/todolist_groups.md: -------------------------------------------------------------------------------- 1 | To-do list groups 2 | ================= 3 | 4 | Endpoints: 5 | 6 | - [List to-do list groups](#list-to-do-list-groups) 7 | - [Get a to-do list group](#get-to-do-list-group) 8 | - [Create a to-do list group](#create-a-to-do-list-group) 9 | - [Reposition a to-do list group](#reposition-a-to-do-list-group) 10 | 11 | List to-do list groups 12 | ---------------------- 13 | 14 | * `GET /buckets/1/todolists/2/groups.json` will return a [paginated list][pagination] of active groups in the project with an ID of `1` and the to-do list with ID of `2`. 15 | 16 | _Optional query parameters_: 17 | 18 | * `status` - when set to `archived` or `trashed`, returns only archived or trashed to-do list groups within this to-do list. 19 | 20 | ###### Example JSON Response 21 | 22 | ```json 23 | [ 24 | { 25 | "id": 1069479100, 26 | "status": "active", 27 | "visible_to_clients": false, 28 | "created_at": "2022-10-21T10:24:24.930Z", 29 | "updated_at": "2022-11-22T08:23:38.003Z", 30 | "title": "Group A", 31 | "inherits_status": true, 32 | "type": "Todolist", 33 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/todolists/1069479100.json", 34 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/todolists/1069479100", 35 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5MTAwP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--7925d04412570c8f9576fa5ead98f77b9d48640c.json", 36 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958497/recordings/1069479100/subscription.json", 37 | "comments_count": 0, 38 | "comments_url": "https://3.basecampapi.com/195539477/buckets/2085958497/recordings/1069479100/comments.json", 39 | "position": 1, 40 | "parent": { 41 | "id": 1069479099, 42 | "title": "Ping pong tournament", 43 | "type": "Todolist", 44 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/todolists/1069479099.json", 45 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/todolists/1069479099" 46 | }, 47 | "bucket": { 48 | "id": 2085958497, 49 | "name": "Honcho Design Newsroom", 50 | "type": "Project" 51 | }, 52 | "creator": { 53 | "id": 1049715925, 54 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTI1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--6a81661a78620c3dfbd47bd56f73be4a144efb77", 55 | "name": "Brian Jenks", 56 | "email_address": "brian@honchodesign.com", 57 | "personable_type": "User", 58 | "title": "International Branding Liason", 59 | "bio": null, 60 | "location": null, 61 | "created_at": "2022-11-22T08:23:22.042Z", 62 | "updated_at": "2022-11-22T08:23:22.042Z", 63 | "admin": false, 64 | "owner": false, 65 | "client": false, 66 | "employee": false, 67 | "time_zone": "Etc/UTC", 68 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBNVkkT4=--d1d91cb4e7b2a143d18329cd4e8ec4d65fbda939/avatar?v=1", 69 | "can_manage_projects": true, 70 | "can_manage_people": true 71 | }, 72 | "description": "", 73 | "completed": false, 74 | "completed_ratio": "0/2", 75 | "name": "Group A", 76 | "todos_url": "https://3.basecampapi.com/195539477/buckets/2085958497/todolists/1069479100/todos.json", 77 | "group_position_url": "https://3.basecampapi.com/195539477/buckets/2085958497/todolists/groups/1069479100/position.json", 78 | "app_todos_url": "https://3.basecamp.com/195539477/buckets/2085958497/todolists/1069479100/todos" 79 | }, 80 | { 81 | "id": 1069479103, 82 | "status": "active", 83 | "visible_to_clients": false, 84 | "created_at": "2022-10-21T08:56:24.930Z", 85 | "updated_at": "2022-11-22T08:23:38.283Z", 86 | "title": "Group B", 87 | "inherits_status": true, 88 | "type": "Todolist", 89 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/todolists/1069479103.json", 90 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/todolists/1069479103", 91 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5MTAzP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--ef5ad3d44bdf9c717ea154529f49d7166f90c5fc.json", 92 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958497/recordings/1069479103/subscription.json", 93 | "comments_count": 0, 94 | "comments_url": "https://3.basecampapi.com/195539477/buckets/2085958497/recordings/1069479103/comments.json", 95 | "position": 2, 96 | "parent": { 97 | "id": 1069479099, 98 | "title": "Ping pong tournament", 99 | "type": "Todolist", 100 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/todolists/1069479099.json", 101 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/todolists/1069479099" 102 | }, 103 | "bucket": { 104 | "id": 2085958497, 105 | "name": "Honcho Design Newsroom", 106 | "type": "Project" 107 | }, 108 | "creator": { 109 | "id": 1049715925, 110 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTI1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--6a81661a78620c3dfbd47bd56f73be4a144efb77", 111 | "name": "Brian Jenks", 112 | "email_address": "brian@honchodesign.com", 113 | "personable_type": "User", 114 | "title": "International Branding Liason", 115 | "bio": null, 116 | "location": null, 117 | "created_at": "2022-11-22T08:23:22.042Z", 118 | "updated_at": "2022-11-22T08:23:22.042Z", 119 | "admin": false, 120 | "owner": false, 121 | "client": false, 122 | "employee": false, 123 | "time_zone": "Etc/UTC", 124 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBNVkkT4=--d1d91cb4e7b2a143d18329cd4e8ec4d65fbda939/avatar?v=1", 125 | "can_manage_projects": true, 126 | "can_manage_people": true 127 | }, 128 | "description": "", 129 | "completed": false, 130 | "completed_ratio": "0/2", 131 | "name": "Group B", 132 | "todos_url": "https://3.basecampapi.com/195539477/buckets/2085958497/todolists/1069479103/todos.json", 133 | "group_position_url": "https://3.basecampapi.com/195539477/buckets/2085958497/todolists/groups/1069479103/position.json", 134 | "app_todos_url": "https://3.basecamp.com/195539477/buckets/2085958497/todolists/1069479103/todos" 135 | } 136 | ] 137 | ``` 138 | 139 | ###### Copy as cURL 140 | 141 | ``` shell 142 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/todolists/2/groups.json 143 | ``` 144 | 145 | Get a to-do list group 146 | ---------------------- 147 | 148 | To-do list groups can be read in exactly the same way as to-do lists. The only difference is a top-level to-do list will 149 | include a groups_url in its response, while a group will have a group_position_url 150 | 151 | * `GET /buckets/1/todolists/3.json` will return the to-do list group with an ID of `3` in the project with an ID of `1`. 152 | 153 | ###### Example JSON Response 154 | 155 | ```json 156 | { 157 | "id": 1069479100, 158 | "status": "active", 159 | "visible_to_clients": false, 160 | "created_at": "2022-10-21T10:24:24.930Z", 161 | "updated_at": "2022-11-22T08:23:38.003Z", 162 | "title": "Group A", 163 | "inherits_status": true, 164 | "type": "Todolist", 165 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/todolists/1069479100.json", 166 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/todolists/1069479100", 167 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5MTAwP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--7925d04412570c8f9576fa5ead98f77b9d48640c.json", 168 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958497/recordings/1069479100/subscription.json", 169 | "comments_count": 0, 170 | "comments_url": "https://3.basecampapi.com/195539477/buckets/2085958497/recordings/1069479100/comments.json", 171 | "position": 1, 172 | "parent": { 173 | "id": 1069479099, 174 | "title": "Ping pong tournament", 175 | "type": "Todolist", 176 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/todolists/1069479099.json", 177 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/todolists/1069479099" 178 | }, 179 | "bucket": { 180 | "id": 2085958497, 181 | "name": "Honcho Design Newsroom", 182 | "type": "Project" 183 | }, 184 | "creator": { 185 | "id": 1049715925, 186 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTI1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--6a81661a78620c3dfbd47bd56f73be4a144efb77", 187 | "name": "Brian Jenks", 188 | "email_address": "brian@honchodesign.com", 189 | "personable_type": "User", 190 | "title": "International Branding Liason", 191 | "bio": null, 192 | "location": null, 193 | "created_at": "2022-11-22T08:23:22.042Z", 194 | "updated_at": "2022-11-22T08:23:22.042Z", 195 | "admin": false, 196 | "owner": false, 197 | "client": false, 198 | "employee": false, 199 | "time_zone": "Etc/UTC", 200 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBNVkkT4=--d1d91cb4e7b2a143d18329cd4e8ec4d65fbda939/avatar?v=1", 201 | "can_manage_projects": true, 202 | "can_manage_people": true 203 | }, 204 | "description": "", 205 | "completed": false, 206 | "completed_ratio": "0/2", 207 | "name": "Group A", 208 | "todos_url": "https://3.basecampapi.com/195539477/buckets/2085958497/todolists/1069479100/todos.json", 209 | "group_position_url": "https://3.basecampapi.com/195539477/buckets/2085958497/todolists/groups/1069479100/position.json", 210 | "app_todos_url": "https://3.basecamp.com/195539477/buckets/2085958497/todolists/1069479100/todos" 211 | } 212 | ``` 213 | 214 | 215 | Create a to-do list group 216 | ------------------------- 217 | 218 | * `POST /buckets/1/todolists/2/groups.json` creates a to-do group within the todolist with ID `2` in the project with id `1`. 219 | 220 | **Required parameters**: `name` of the to-do list group. 221 | 222 | _Optional parameters_: 223 | 224 | * `color` - the color. Available values: `[ white red orange yellow green blue aqua purple gray pink brown ]` 225 | 226 | 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](#get-a-to-do-list) endpoint for more info on the payload. 227 | 228 | ###### Example JSON Request 229 | 230 | ``` json 231 | { 232 | "name": "The Spencer Davis Group", 233 | } 234 | ``` 235 | 236 | ###### Copy as cURL 237 | 238 | ``` shell 239 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 240 | -d '{"name":"The Spencer Davis Group"}' \ 241 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/todolists/2/groups.json 242 | ``` 243 | 244 | Reposition a to-do list group 245 | ----------------------------- 246 | 247 | * `PUT /buckets/1/todolists/groups/3/position.json` allows changing the position of the to-do list group with an ID of `3` in the project with ID `1`. 248 | 249 | **Required parameters**: `position` greater than or equal to one. 250 | 251 | This endpoint will return `204 No Content` if the update was a success. 252 | 253 | ###### Example JSON Request 254 | 255 | ``` json 256 | { 257 | "position": 3 258 | } 259 | ``` 260 | 261 | ###### Copy as cURL 262 | 263 | ``` shell 264 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 265 | -d '{"position":3}' -X PUT \ 266 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/todolists/groups/3/position.json 267 | ``` 268 | 269 | [pagination]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination 270 | -------------------------------------------------------------------------------- /sections/todolists.md: -------------------------------------------------------------------------------- 1 | To-do lists 2 | =========== 3 | 4 | Endpoints: 5 | 6 | - [Get to-do lists](#get-to-do-lists) 7 | - [Get a to-do list](#get-a-to-do-list) 8 | - [Create a to-do list](#create-a-to-do-list) 9 | - [Update a to-do list](#update-a-to-do-list) 10 | - [Trash a to-do list][trash] 11 | 12 | Get to-do lists 13 | --------------- 14 | 15 | * `GET /buckets/1/todosets/3/todolists.json` will return a [paginated list][pagination] of active to-do lists in the project with an ID of `1` and the to-do set with ID of `3`. 16 | 17 | To get the to-do set ID for a project, see the [Get to-do set][todoset] endpoint. 18 | 19 | _Optional query parameters_: 20 | 21 | * `status` - when set to `archived` or `trashed`, will return archived or trashed to-do lists that are in this to-do set. 22 | 23 | ###### Example JSON Response 24 | 25 | ```json 26 | [ 27 | { 28 | "id": 1069479520, 29 | "status": "active", 30 | "visible_to_clients": false, 31 | "created_at": "2022-11-19T10:49:58.169Z", 32 | "updated_at": "2022-11-22T13:36:50.727Z", 33 | "title": "Strategy ideas", 34 | "inherits_status": true, 35 | "type": "Todolist", 36 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/todolists/1069479520.json", 37 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/todolists/1069479520", 38 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5NTIwP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--24332fbdc81b06784de7e8f2b6c1e29021bbae58.json", 39 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479520/subscription.json", 40 | "comments_count": 0, 41 | "comments_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479520/comments.json", 42 | "position": 1, 43 | "parent": { 44 | "id": 1069479339, 45 | "title": "To-dos", 46 | "type": "Todoset", 47 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/todosets/1069479339.json", 48 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/todosets/1069479339" 49 | }, 50 | "bucket": { 51 | "id": 2085958499, 52 | "name": "The Leto Laptop", 53 | "type": "Project" 54 | }, 55 | "creator": { 56 | "id": 1049715915, 57 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--aeb392ebf54ffd820e45f27add22bae3a8c7da56", 58 | "name": "Annie Bryan", 59 | "email_address": "annie@honchodesign.com", 60 | "personable_type": "User", 61 | "title": "Central Markets Manager", 62 | "bio": "To open a store is easy, to keep it open is an art", 63 | "location": null, 64 | "created_at": "2022-11-22T08:23:21.911Z", 65 | "updated_at": "2022-11-22T08:23:21.911Z", 66 | "admin": false, 67 | "owner": false, 68 | "client": false, 69 | "employee": true, 70 | "time_zone": "America/Chicago", 71 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMtkkT4=--9927c47a4cbee30a7f9aea667882496aba799149/avatar?v=1", 72 | "company": { 73 | "id": 1033447817, 74 | "name": "Honcho Design" 75 | }, 76 | "can_manage_projects": true, 77 | "can_manage_people": true 78 | }, 79 | "description": "", 80 | "completed": false, 81 | "completed_ratio": "2/5", 82 | "name": "Strategy ideas", 83 | "todos_url": "https://3.basecampapi.com/195539477/buckets/2085958499/todolists/1069479520/todos.json", 84 | "groups_url": "https://3.basecampapi.com/195539477/buckets/2085958499/todolists/1069479520/groups.json", 85 | "app_todos_url": "https://3.basecamp.com/195539477/buckets/2085958499/todolists/1069479520/todos" 86 | } 87 | ] 88 | ``` 89 | 90 | ###### Copy as cURL 91 | 92 | ``` shell 93 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/todosets/3/todolists.json 94 | ``` 95 | 96 | 97 | Get a to-do list 98 | ---------------- 99 | 100 | * `GET /buckets/1/todolists/2.json` will return the to-do list with an ID of `2` in the project with an ID of `1`. 101 | 102 | ###### Example JSON Response 103 | 104 | ```json 105 | { 106 | "id": 1069479369, 107 | "status": "active", 108 | "visible_to_clients": false, 109 | "created_at": "2022-10-31T08:24:58.169Z", 110 | "updated_at": "2022-11-22T08:24:00.825Z", 111 | "title": "Background and research", 112 | "inherits_status": true, 113 | "type": "Todolist", 114 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/todolists/1069479369.json", 115 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/todolists/1069479369", 116 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5MzY5P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--4b6309a7d4c2ec4c0ca573bd0caeedbcb3e49a2f.json", 117 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479369/subscription.json", 118 | "comments_count": 0, 119 | "comments_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479369/comments.json", 120 | "position": 10, 121 | "parent": { 122 | "id": 1069479339, 123 | "title": "To-dos", 124 | "type": "Todoset", 125 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/todosets/1069479339.json", 126 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/todosets/1069479339" 127 | }, 128 | "bucket": { 129 | "id": 2085958499, 130 | "name": "The Leto Laptop", 131 | "type": "Project" 132 | }, 133 | "creator": { 134 | "id": 1049715923, 135 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTIzP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--cc7313cd0fef7654f37f813c000bf892d80e2e2f", 136 | "name": "Andrew Wong", 137 | "email_address": "andrew@honchodesign.com", 138 | "personable_type": "User", 139 | "title": "Senior Branding Strategist", 140 | "bio": null, 141 | "location": null, 142 | "created_at": "2022-11-22T08:23:22.017Z", 143 | "updated_at": "2022-11-22T08:23:22.017Z", 144 | "admin": false, 145 | "owner": false, 146 | "client": false, 147 | "employee": false, 148 | "time_zone": "Etc/UTC", 149 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBNNkkT4=--e3c2676dde30e7c13f87642e3a3dd46ad657f731/avatar?v=1", 150 | "can_manage_projects": true, 151 | "can_manage_people": true 152 | }, 153 | "description": "", 154 | "completed": false, 155 | "completed_ratio": "0/4", 156 | "name": "Background and research", 157 | "todos_url": "https://3.basecampapi.com/195539477/buckets/2085958499/todolists/1069479369/todos.json", 158 | "groups_url": "https://3.basecampapi.com/195539477/buckets/2085958499/todolists/1069479369/groups.json", 159 | "app_todos_url": "https://3.basecamp.com/195539477/buckets/2085958499/todolists/1069479369/todos" 160 | } 161 | ``` 162 | 163 | ###### Copy as cURL 164 | 165 | ``` shell 166 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/todolists/2.json 167 | ``` 168 | 169 | 170 | Create a to-do list 171 | ------------------- 172 | 173 | * `POST /buckets/1/todosets/3/todolists.json` creates a to-do list in the project with ID `1` and under the to-do set with an ID of `3`. 174 | 175 | **Required parameters**: `name` of the to-do list. 176 | 177 | _Optional parameters_: `description` containing information about the to-do list. See our [Rich text guide][rich] for what HTML tags are allowed. 178 | 179 | 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](#get-a-to-do-list) endpoint for more info on the payload. 180 | 181 | ###### Example JSON Request 182 | 183 | ``` json 184 | { 185 | "name": "Launch", 186 | "description": "
Finish it!
" 187 | } 188 | ``` 189 | 190 | ###### Copy as cURL 191 | 192 | ``` shell 193 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 194 | -d '{"name":"Launch","description":"
Finish it!
"}' \ 195 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/todosets/3/todolists.json 196 | ``` 197 | 198 | 199 | Update a to-do list 200 | ------------------- 201 | 202 | * `PUT /buckets/1/todolists/2.json` allows changing the name and description of the to-do list with an ID of `2` in the project with ID `1`. 203 | 204 | 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](#get-a-to-do-list) endpoint for more info on the payload. 205 | 206 | **Required parameters**: Pass all existing parameters in addition to those being updated. Omitting a parameter will clear its value. 207 | 208 | * `name` of the to-do list. This one is always required, it can't be omitted as it can't be blank. 209 | 210 | * `description` containing information about the to-do list. See our [Rich text guide][rich] for what HTML tags are allowed. 211 | 212 | ###### Example JSON Request 213 | 214 | ``` json 215 | { 216 | "name": "Relaunch", 217 | "description": "
Try this again.
" 218 | } 219 | ``` 220 | 221 | ###### Copy as cURL 222 | 223 | ``` shell 224 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 225 | -d '{"name":"Relaunch","description":"
Try this again.
"}' -X PUT \ 226 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/todolists/2.json 227 | ``` 228 | 229 | 230 | [trash]: https://github.com/basecamp/bc3-api/blob/master/sections/recordings.md#trash-a-recording 231 | [pagination]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination 232 | [todoset]: https://github.com/basecamp/bc3-api/blob/master/sections/todosets.md#get-to-do-set 233 | [todos]: https://github.com/basecamp/bc3-api/blob/master/sections/todos.md#to-dos 234 | [rich]: https://github.com/basecamp/bc3-api/blob/master/sections/rich_text.md 235 | -------------------------------------------------------------------------------- /sections/todosets.md: -------------------------------------------------------------------------------- 1 | To-do sets 2 | ========== 3 | 4 | All to-do lists under a project are children of a to-do set resource. 5 | 6 | Endpoints: 7 | 8 | - [Get to-do set](#get-to-do-set) 9 | 10 | 11 | Get to-do set 12 | ------------- 13 | 14 | * `GET /buckets/1/todosets/2.json` will return the to-do set for the project with an ID of `1` and a to-do set ID of `2`. 15 | 16 | To get the to-do set ID for a project, see the [Get a project][1] endpoint's `dock` payload. To retrieve its to-do lists, see the [Get to-do lists][2] endpoint. 17 | 18 | ###### Example JSON Response 19 | 20 | ```json 21 | { 22 | "id": 1069479339, 23 | "status": "active", 24 | "visible_to_clients": false, 25 | "created_at": "2022-11-22T08:23:58.206Z", 26 | "updated_at": "2022-11-22T13:36:50.731Z", 27 | "title": "To-dos", 28 | "inherits_status": true, 29 | "type": "Todoset", 30 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/todosets/1069479339.json", 31 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/todosets/1069479339", 32 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5MzM5P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--51a5eae687ae2189e66551c48e347d8666aa7629.json", 33 | "position": 2, 34 | "bucket": { 35 | "id": 2085958499, 36 | "name": "The Leto Laptop", 37 | "type": "Project" 38 | }, 39 | "creator": { 40 | "id": 1049715914, 41 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 42 | "name": "Victor Cooper", 43 | "email_address": "victor@honchodesign.com", 44 | "personable_type": "User", 45 | "title": "Chief Strategist", 46 | "bio": "Don’t let your dreams be dreams", 47 | "location": "Chicago, IL", 48 | "created_at": "2022-11-22T08:23:21.732Z", 49 | "updated_at": "2022-11-22T08:23:21.904Z", 50 | "admin": true, 51 | "owner": true, 52 | "client": false, 53 | "employee": true, 54 | "time_zone": "America/Chicago", 55 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 56 | "company": { 57 | "id": 1033447817, 58 | "name": "Honcho Design" 59 | }, 60 | "can_manage_projects": true, 61 | "can_manage_people": true 62 | }, 63 | "completed": false, 64 | "completed_ratio": "14/60", 65 | "name": "To-dos", 66 | "todolists_count": 10, 67 | "todolists_url": "https://3.basecampapi.com/195539477/buckets/2085958499/todosets/1069479339/todolists.json", 68 | "app_todoslists_url": "https://3.basecamp.com/195539477/buckets/2085958499/todosets/1069479339/todolists" 69 | } 70 | ``` 71 | 72 | ###### Copy as cURL 73 | 74 | ``` shell 75 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/todosets/2.json 76 | ``` 77 | 78 | 79 | [1]: https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#get-a-project 80 | [2]: https://github.com/basecamp/bc3-api/blob/master/sections/todolists.md#get-to-do-lists 81 | [3]: https://github.com/basecamp/bc3-api/blob/master/sections/recordings.md#trash-a-recording 82 | -------------------------------------------------------------------------------- /sections/uploads.md: -------------------------------------------------------------------------------- 1 | Uploads 2 | ======= 3 | 4 | Endpoints: 5 | 6 | - [Get uploads](#get-uploads) 7 | - [Get an upload](#get-an-upload) 8 | - [Create an upload](#create-an-upload) 9 | - [Update an upload](#update-an-upload) 10 | - [Trash an upload][trash] 11 | 12 | Get uploads 13 | ----------- 14 | 15 | * `GET /buckets/1/vaults/2/uploads.json` will return a [paginated list][pagination] of active uploads in the project with an ID of `1` and the [vault][vaults] with ID of `2`. 16 | 17 | ###### Example JSON Response 18 | 19 | ```json 20 | [ 21 | { 22 | "id": 1069479848, 23 | "status": "active", 24 | "visible_to_clients": false, 25 | "created_at": "2022-11-22T08:25:04.400Z", 26 | "updated_at": "2022-11-22T08:25:04.408Z", 27 | "title": "company-logo.png", 28 | "inherits_status": true, 29 | "type": "Upload", 30 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/uploads/1069479848.json", 31 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/uploads/1069479848", 32 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5ODQ4P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--b125776d2d29e638ecfefc0fd5bf4957f79ae0d5.json", 33 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479848/subscription.json", 34 | "comments_count": 0, 35 | "comments_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479848/comments.json", 36 | "position": 1, 37 | "parent": { 38 | "id": 1069479340, 39 | "title": "Docs & Files", 40 | "type": "Vault", 41 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/vaults/1069479340.json", 42 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/vaults/1069479340" 43 | }, 44 | "bucket": { 45 | "id": 2085958499, 46 | "name": "The Leto Laptop", 47 | "type": "Project" 48 | }, 49 | "creator": { 50 | "id": 1049715914, 51 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 52 | "name": "Victor Cooper", 53 | "email_address": "victor@honchodesign.com", 54 | "personable_type": "User", 55 | "title": "Chief Strategist", 56 | "bio": "Don’t let your dreams be dreams", 57 | "location": "Chicago, IL", 58 | "created_at": "2022-11-22T08:23:21.732Z", 59 | "updated_at": "2022-11-22T08:23:21.904Z", 60 | "admin": true, 61 | "owner": true, 62 | "client": false, 63 | "employee": true, 64 | "time_zone": "America/Chicago", 65 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 66 | "company": { 67 | "id": 1033447817, 68 | "name": "Honcho Design" 69 | }, 70 | "can_manage_projects": true, 71 | "can_manage_people": true 72 | }, 73 | "description": "
Check out the new logo
", 74 | "content_type": "image/png", 75 | "byte_size": 1281, 76 | "filename": "company-logo.png", 77 | "download_url": "https://3.basecampapi.com/195539477/buckets/2085958499/uploads/1069479848/download/company-logo.png", 78 | "app_download_url": "http://storage.3.basecamp.test/195539477/buckets/2085958499/uploads/1069479848/download/company-logo.png", 79 | "width": 164, 80 | "height": 39 81 | } 82 | ] 83 | ``` 84 | 85 | ###### Copy as cURL 86 | 87 | ``` shell 88 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/vaults/2/uploads.json 89 | ``` 90 | 91 | Get an upload 92 | ------------- 93 | 94 | * `GET /buckets/1/uploads/2.json` will return the upload with an ID of `2` in the project with an ID of `1`. 95 | 96 | ###### Example JSON Response 97 | 98 | ```json 99 | { 100 | "id": 1069479848, 101 | "status": "active", 102 | "visible_to_clients": false, 103 | "created_at": "2022-11-22T08:25:04.400Z", 104 | "updated_at": "2022-11-22T08:25:04.408Z", 105 | "title": "company-logo.png", 106 | "inherits_status": true, 107 | "type": "Upload", 108 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/uploads/1069479848.json", 109 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/uploads/1069479848", 110 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5ODQ4P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--b125776d2d29e638ecfefc0fd5bf4957f79ae0d5.json", 111 | "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479848/subscription.json", 112 | "comments_count": 0, 113 | "comments_url": "https://3.basecampapi.com/195539477/buckets/2085958499/recordings/1069479848/comments.json", 114 | "position": 1, 115 | "parent": { 116 | "id": 1069479340, 117 | "title": "Docs & Files", 118 | "type": "Vault", 119 | "url": "https://3.basecampapi.com/195539477/buckets/2085958499/vaults/1069479340.json", 120 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958499/vaults/1069479340" 121 | }, 122 | "bucket": { 123 | "id": 2085958499, 124 | "name": "The Leto Laptop", 125 | "type": "Project" 126 | }, 127 | "creator": { 128 | "id": 1049715914, 129 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 130 | "name": "Victor Cooper", 131 | "email_address": "victor@honchodesign.com", 132 | "personable_type": "User", 133 | "title": "Chief Strategist", 134 | "bio": "Don’t let your dreams be dreams", 135 | "location": "Chicago, IL", 136 | "created_at": "2022-11-22T08:23:21.732Z", 137 | "updated_at": "2022-11-22T08:23:21.904Z", 138 | "admin": true, 139 | "owner": true, 140 | "client": false, 141 | "employee": true, 142 | "time_zone": "America/Chicago", 143 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 144 | "company": { 145 | "id": 1033447817, 146 | "name": "Honcho Design" 147 | }, 148 | "can_manage_projects": true, 149 | "can_manage_people": true 150 | }, 151 | "description": "
Check out the new logo
", 152 | "content_type": "image/png", 153 | "byte_size": 1281, 154 | "filename": "company-logo.png", 155 | "download_url": "https://3.basecampapi.com/195539477/buckets/2085958499/uploads/1069479848/download/company-logo.png", 156 | "app_download_url": "http://storage.3.basecamp.test/195539477/buckets/2085958499/uploads/1069479848/download/company-logo.png", 157 | "width": 164, 158 | "height": 39 159 | } 160 | ``` 161 | 162 | 163 | ###### Copy as cURL 164 | 165 | ``` shell 166 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/uploads/2.json 167 | ``` 168 | 169 | Create an upload 170 | ---------------- 171 | 172 | * `POST /buckets/1/vaults/2/uploads.json` creates an upload in the project with ID `1` and under the vault with an ID of `2`. 173 | 174 | **Required parameters**: `attachable_sgid` for an uploaded attachment. See the [Create an attachment][attachments] endpoint for more info on uploading attachments. 175 | 176 | _Optional parameters_: 177 | * `description` - containing information about the upload. See our [Rich text guide][rich] for what HTML tags allowed. 178 | * `base_name` - an new file name for the upload. `base_name` should be a file name *without* an extension (e.g. `"pizza"` for `"pizza.png"`). 179 | 180 | This endpoint will return `201 Created` with the current JSON representation of the upload if the creation was a success. See the [Get an upload](#get-an-upload) endpoint for more info on the payload. 181 | 182 | ###### Example JSON Request 183 | 184 | ``` json 185 | { 186 | "attachable_sgid": "BAh2CEkiCGdpZAY6BkVUSSIsZ2lkOi7vYmMzL0F0dGFjaG1lbnQvNzM4NDcyNj9leHBpcmVzX2luBjsAVEkiDHB1cnBvc2UGOwBUSSIPYXR0YWNoYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--13982201abe18044c897e32979c7dccfe8add9c1", 187 | "description": "
Yum
", 188 | "base_name": "yummy_pizza" 189 | } 190 | ``` 191 | 192 | ###### Copy as cURL 193 | 194 | ``` shell 195 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 196 | -d '{"attachable_sgid":"BAh…9c1","description":"
Yum
","base_name":"yummy_pizza"}' \ 197 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/vaults/2/uploads.json 198 | ``` 199 | 200 | Update an upload 201 | ---------------- 202 | 203 | * `PUT /buckets/1/uploads/2.json` allows changing the `description` and `base_name` of the upload with an ID of `2` in the project with ID `1`. 204 | 205 | This endpoint will return `200 OK` with the current JSON representation of the upload if the update was a success. See the [Get an upload](#get-an-upload) endpoint for more info on the payload. 206 | 207 | ###### Example JSON Request 208 | 209 | ``` json 210 | { 211 | "description": "
Meh
", 212 | "base_name": "old_pizza" 213 | } 214 | ``` 215 | 216 | ###### Copy as cURL 217 | 218 | ``` shell 219 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 220 | -d '{"description":"
Meh
","base_name":"old_pizza"}' -X PUT \ 221 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/uploads/2.json 222 | ``` 223 | 224 | [pagination]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination 225 | [attachments]: https://github.com/basecamp/bc3-api/blob/master/sections/attachments.md#create-an-attachment 226 | [trash]: https://github.com/basecamp/bc3-api/blob/master/sections/recordings.md#trash-a-recording 227 | [vaults]: https://github.com/basecamp/bc3-api/blob/master/sections/vaults.md#vaults 228 | [rich]: https://github.com/basecamp/bc3-api/blob/master/sections/rich_text.md 229 | -------------------------------------------------------------------------------- /sections/vaults.md: -------------------------------------------------------------------------------- 1 | Vaults 2 | ====== 3 | 4 | All projects have a primary vault (folder), to get its ID see the [Get a project][project] endpoint's `dock` payload. Additional vaults may be nested under the primary vault or any child vault. 5 | 6 | Endpoints: 7 | 8 | - [Get vaults](#get-vaults) 9 | - [Get a vault](#get-a-vault) 10 | - [Create a vault](#create-a-vault) 11 | - [Update a vault](#update-a-vault) 12 | 13 | Get vaults 14 | ---------- 15 | 16 | * `GET /buckets/1/vaults/2/vaults.json` will return a [paginated list][pagination] of vaults in the project with an ID of `1` and the vault with ID of `2`. 17 | 18 | ###### Example JSON Response 19 | 20 | ```json 21 | [ 22 | { 23 | "id": 1069479099, 24 | "status": "active", 25 | "visible_to_clients": false, 26 | "created_at": "2022-10-14T17:36:37.216Z", 27 | "updated_at": "2022-10-14T17:36:37.216Z", 28 | "title": "Benefits", 29 | "inherits_status": true, 30 | "type": "Vault", 31 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/vaults/1069479099.json", 32 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/vaults/1069479099", 33 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc5MDk5P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--339c1f524eabce1418819d1259d8b0b8804199c0.json", 34 | "position": 1, 35 | "parent": { 36 | "id": 1069479098, 37 | "title": "HR Stuff", 38 | "type": "Vault", 39 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/vaults/1069479098.json", 40 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/vaults/1069479098" 41 | }, 42 | "bucket": { 43 | "id": 2085958497, 44 | "name": "Honcho Design Newsroom", 45 | "type": "Project" 46 | }, 47 | "creator": { 48 | "id": 1049715914, 49 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 50 | "name": "Victor Cooper", 51 | "email_address": "victor@honchodesign.com", 52 | "personable_type": "User", 53 | "title": "Chief Strategist", 54 | "bio": "Don’t let your dreams be dreams", 55 | "location": "Chicago, IL", 56 | "created_at": "2022-11-25T16:24:33.557Z", 57 | "updated_at": "2022-11-25T16:24:33.854Z", 58 | "admin": true, 59 | "owner": true, 60 | "client": false, 61 | "employee": true, 62 | "time_zone": "America/Chicago", 63 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 64 | "company": { 65 | "id": 1033447817, 66 | "name": "Honcho Design" 67 | }, 68 | "can_manage_projects": true, 69 | "can_manage_people": true 70 | }, 71 | "documents_count": 0, 72 | "documents_url": "https://3.basecampapi.com/195539477/buckets/2085958497/vaults/1069479099/documents.json", 73 | "uploads_count": 0, 74 | "uploads_url": "https://3.basecampapi.com/195539477/buckets/2085958497/vaults/1069479099/uploads.json", 75 | "vaults_count": 0, 76 | "vaults_url": "https://3.basecampapi.com/195539477/buckets/2085958497/vaults/1069479099/vaults.json" 77 | } 78 | ] 79 | ``` 80 | 81 | ###### Copy as cURL 82 | 83 | ``` shell 84 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/vaults/2/vaults.json 85 | ``` 86 | 87 | Get a vault 88 | ----------- 89 | 90 | * `GET /buckets/1/vaults/2.json` will return the vault with an ID of `2` in the project with an ID of `1`. 91 | 92 | ###### Example JSON Response 93 | 94 | ```json 95 | { 96 | "id": 1069478932, 97 | "status": "active", 98 | "visible_to_clients": false, 99 | "created_at": "2022-11-25T16:24:37.280Z", 100 | "updated_at": "2022-11-25T16:24:50.564Z", 101 | "title": "Docs & Files", 102 | "inherits_status": true, 103 | "type": "Vault", 104 | "url": "https://3.basecampapi.com/195539477/buckets/2085958497/vaults/1069478932.json", 105 | "app_url": "https://3.basecamp.com/195539477/buckets/2085958497/vaults/1069478932", 106 | "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSIuZ2lkOi8vYmMzL1JlY29yZGluZy8xMDY5NDc4OTMyP2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg1yZWFkYWJsZQY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--019700aaa4b8222137474a665bd3f88dc0329ad1.json", 107 | "position": 3, 108 | "bucket": { 109 | "id": 2085958497, 110 | "name": "Honcho Design Newsroom", 111 | "type": "Project" 112 | }, 113 | "creator": { 114 | "id": 1049715914, 115 | "attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE0P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--ff006accb6e013cca785190fa38f42c091d24f1e", 116 | "name": "Victor Cooper", 117 | "email_address": "victor@honchodesign.com", 118 | "personable_type": "User", 119 | "title": "Chief Strategist", 120 | "bio": "Don’t let your dreams be dreams", 121 | "location": "Chicago, IL", 122 | "created_at": "2022-11-25T16:24:33.557Z", 123 | "updated_at": "2022-11-25T16:24:33.854Z", 124 | "admin": true, 125 | "owner": true, 126 | "client": false, 127 | "employee": true, 128 | "time_zone": "America/Chicago", 129 | "avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMpkkT4=--5520caeec1845b5090bbfc993ffe8eca8d138e14/avatar?v=1", 130 | "company": { 131 | "id": 1033447817, 132 | "name": "Honcho Design" 133 | }, 134 | "can_manage_projects": true, 135 | "can_manage_people": true 136 | }, 137 | "documents_count": 0, 138 | "documents_url": "https://3.basecampapi.com/195539477/buckets/2085958497/vaults/1069478932/documents.json", 139 | "uploads_count": 0, 140 | "uploads_url": "https://3.basecampapi.com/195539477/buckets/2085958497/vaults/1069478932/uploads.json", 141 | "vaults_count": 0, 142 | "vaults_url": "https://3.basecampapi.com/195539477/buckets/2085958497/vaults/1069478932/vaults.json" 143 | } 144 | ``` 145 | 146 | ###### Copy as cURL 147 | 148 | ``` shell 149 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/vaults/2.json 150 | ``` 151 | 152 | Create a vault 153 | -------------- 154 | 155 | * `POST /buckets/1/vaults/2/vaults.json` creates a vault in the project with ID `1` and under the vault with an ID of `2`. 156 | 157 | **Required parameters**: `title` for the name of the vault. 158 | 159 | This endpoint will return `201 Created` with the current JSON representation of the vault if the creation was a success. See the [Get a vault](#get-a-vault) endpoint for more info on the payload. 160 | 161 | ###### Example JSON Request 162 | 163 | ``` json 164 | { 165 | "title": "Materials" 166 | } 167 | ``` 168 | 169 | ###### Copy as cURL 170 | 171 | ``` shell 172 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 173 | -d '{"title":"Materials"}' \ 174 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/vaults/2/vaults.json 175 | ``` 176 | 177 | Update a vault 178 | -------------- 179 | 180 | * `PUT /buckets/1/vaults/3.json` allows changing the title of the vault with an ID of `3` in the project with ID `1`. 181 | 182 | This endpoint will return `200 OK` with the current JSON representation of the to-do if the update was a success. See the [Get a vault](#get-a-vault) endpoint for more info on the payload. 183 | 184 | ###### Example JSON Request 185 | 186 | ``` json 187 | { 188 | "title": "Important Materials" 189 | } 190 | ``` 191 | 192 | ###### Copy as cURL 193 | 194 | ``` shell 195 | curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ 196 | -d '{"title":"Important Materials"}' -X PUT \ 197 | https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/vaults/3.json 198 | ``` 199 | 200 | [project]: https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#get-a-project 201 | [pagination]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination 202 | --------------------------------------------------------------------------------