├── README.md └── sections ├── account.md ├── attachments.md ├── calendar_entries.md ├── categories.md ├── comments.md ├── companies.md ├── data_reference.md ├── files.md ├── messages.md ├── people.md ├── projects.md ├── time_tracking.md ├── todo_list_items.md └── todo_lists.md /README.md: -------------------------------------------------------------------------------- 1 | Basecamp Classic API 2 | ==================== 3 | 4 | This is the API for Basecamp Classic (basecamphq.com). It is not compatible with the [Basecamp 2 API](https://github.com/basecamp/bcx-api) or [Basecamp 3 API](https://github.com/basecamp/bc3-api). 5 | 6 | The Basecamp Classic API is implemented as vanilla XML over HTTP using all four verbs (GET/POST/PUT/DELETE). Every resource, like Post, Comment, or TodoList, has their own URL and are manipulated in isolation. We've tried to make the API follow the REST principles as much as we can. 7 | 8 | 9 | Wrappers and example code 10 | ------------------------- 11 | 12 | * [Ruby basecamp-wrapper by anibalcucco](https://github.com/anibalcucco/basecamp-wrapper) 13 | * [Python Basecamp Wrapper by Jochen](http://homework.nwsnet.de/products/3cd4_basecamp-wrappera) 14 | * [Python basecampreporting by cmheisel](http://github.com/cmheisel/basecampreporting/) 15 | * [PHP API Wrapper by sirprize](http://github.com/sirprize/basecamp) 16 | * [Java API Wrapper by johndavidjohn](https://github.com/jondavidjohn/java-basecamp-api-wrapper) 17 | 18 | Wrote your own API wrapper? Feel free to open a pull request and add to this list! 19 | 20 | 21 | Authentication 22 | -------------- 23 | 24 | If you're making a private integration with Basecamp Classic for your own purposes, you can use HTTP Basic authentication. This is secure since all requests in the new Basecamp use SSL. 25 | 26 | Your API token can be found by logging into your Basecamp Classic account, clicking on the "My Info" link in the upper-right, and then clicking the "Show your tokens" at the bottom (under "Authentication tokens"). 27 | 28 | If you're making a public integration with Basecamp Classic for others to enjoy, you can also use OAuth 2. This allows users to authorize your application to use Basecamp Classic on their behalf without having to copy/paste API tokens or touch sensitive login info. 29 | 30 | Read the [Basecamp API Authentication Guide](https://github.com/basecamp/api/tree/master/sections/authentication.md) for more info on using OAuth. 31 | 32 | 33 | 34 | Making a request 35 | --------------- 36 | 37 | Be sure to set both the 'Content-Type' and 'Accept' headers to 'application/xml' to identify the request and response format. Example with Curl: 38 | 39 | curl -H 'Accept: application/xml' -H 'Content-Type: application/xml' \ 40 | -u hoodlum:up2n0g00d \ 41 | -d '...' \ 42 | https://url/todo_lists/123/todo_items.xml 43 | 44 | 45 | Identify your app 46 | ----------------- 47 | 48 | You should include a `User-Agent` header with the name of your application and a link to it or your email address so we can get in touch in case you're doing something wrong (so we may warn you before you're blacklisted) or something awesome (so we may congratulate you). Here's a couple of examples: 49 | 50 | User-Agent: Freshbooks (http://freshbooks.com/contact.php) 51 | User-Agent: Fabian's Ingenious Integration (fabian@example.com) 52 | 53 | Requests made without an identifiable User-Agent are much more tightly rate-limited. 54 | 55 | API Endpoints 56 | ------------- 57 | 58 | * [Account](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/account.md) 59 | * [Projects](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/projects.md) 60 | * [People](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/people.md) 61 | * [Companies](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/companies.md) 62 | * [Categories](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/categories.md) 63 | * [Messages](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/messages.md) 64 | * [Comments](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/comments.md) 65 | * [Todo Lists](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/todo_lists.md) 66 | * [Todo List Items](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/todo_list_items.md) 67 | * [Calendar Entries](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/calendar_entries.md) 68 | * [Time Tracking](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/time_tracking.md) 69 | * [Attachments](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/attachments.md) 70 | * [Files](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/files.md) 71 | 72 | (Hint: Press `t` to enable the file finder and type out the endpoint you need!) 73 | 74 | Need a sample of each XML blob will look like? Check out the [Data Reference](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/data_reference.md). 75 | 76 | 77 | Responses 78 | --------- 79 | 80 | If a request succeeds, it will return a status code in the 200 range and often, an XML-formatted response. Note that, in general, if a request causes a new record to be created (like a new message, or to-do item, etc.), the response will use the "201 Created" status. Any other successful operation (like a successful query, delete, or update) will return a 200 status code. 81 | 82 | 83 | Rate limiting 84 | ------------- 85 | API requests are subject to rate limiting. Design your API client to expect and properly respond when you encounter a rate-limited response. 86 | 87 | A rate limit is based on the number of requests made within a time window. For example, 100 requests within a minute. If you make more requests than that in a minute, subsequent requests will be rate-limited for the following minute. 88 | 89 | When you exceed a rate limit, you'll get a 503 or 429 response with a Retry-After header indicating how many seconds to wait before trying again. Wait until that time has elapsed and resume your requests. Retrying the request before the time window has elapsed will flag your API client for flooding. 90 | 91 | Rate limits in effect as of August 2014, per source IP and Basecamp account: 92 | 93 | * GET: 500 requests per 10 seconds 94 | * Non-GET: 100 requests per 10 seconds 95 | * No User-Agent header: 60 requests per minute 96 | 97 | It's especially important to set an identifiable User-Agent header. If you exceed 60 requests in a minute, your client will need to wait a full minute to resume. 98 | 99 | SSL Usage 100 | --------- 101 | 102 | A non-SSL request made against an account that has SSL enabled (and vice versa) will receive a "302 Found" response. The Location header will contain the correct URI. 103 | 104 | If SSL is enabled for your account, ensure that you're using https. If it's not, ensure you're using http. 105 | 106 | 107 | Documentation Conventions 108 | ------------------------- 109 | 110 | To make things easier to understand, the following notation is used: 111 | 112 | * `#{text}`: Indicates text that should be replaced by your own data 113 | * `...`: Indicates content from the response has been elided for brevity in documentation. See the list of data responses at the end of the page for a full description of the format of that response type. 114 | 115 | 116 | Help us make it better 117 | ---------------------- 118 | 119 | Please tell us how we can make this API better. If you have a specific feature request or if you found a bug, please [open a support ticket](http://help.basecamp.com/tickets/new). Also, feel free to fork these docs and send a pull request with improvements! 120 | 121 | To talk with us and other developers about the API, [post a question on StackOverflow](http://stackoverflow.com/questions/ask) tagged `basecamp` or [open a support ticket](http://help.basecamp.com/tickets/new). 122 | -------------------------------------------------------------------------------- /sections/account.md: -------------------------------------------------------------------------------- 1 | Account 2 | ======= 3 | 4 | `GET /account.xml` returns info about the current Basecamp Classic account 5 | 6 | This endpoint includes: 7 | 8 | * account id and name 9 | * account holder’s person id 10 | * primary company’s id 11 | * whether SSL is enabled 12 | * whether email notification is enabled 13 | * whether time tracking is enabled 14 | * subscription: plan name, maximum number of projects and writeboards, maximum storage in bytes, availability of SSL and time tracking 15 | * last-update timestamp 16 | * default post and attachment categories 17 | 18 | **Response:** 19 | 20 | ``` xml 21 | 22 | 1 23 | Your Company 24 | 1 25 | 1 26 | true 27 | true 28 | true 29 | 2009-10-09T17:52:46Z 30 | 31 | Premium 32 | Infinity 33 | 100 34 | 32212254720 35 | true 36 | true 37 | 38 | 39 | Documents 40 | Pictures 41 | Sounds 42 | 43 | 44 | Design 45 | Code 46 | Copywriting 47 | Transcripts 48 | Assets 49 | Miscellaneous 50 | 51 | 52 | ``` 53 | -------------------------------------------------------------------------------- /sections/attachments.md: -------------------------------------------------------------------------------- 1 | Attachments 2 | =========== 3 | 4 | For accessing files on a given project, please see the [Files API](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/files.md). 5 | 6 | Attaching files via the API 7 | --------------------------- 8 | 9 | Some operations, like creating messages or comments, or updating existing messages or comments, allow you to attach a file to the record. To do this via the API, you need to send a POST request to the `/upload` URI, with the HTTP Accept header set to `application/xml`. The body of the request should be the content of the file you want to attach: 10 | 11 | POST /upload HTTP/1.0 12 | Accept: application/xml 13 | Content-Type: application/octet-stream 14 | Content-Length: 23123 15 | 16 | ... (file contents go here) 17 | 18 | If the upload succeeds, you'll get an XML response back, telling you the ID of your upload. (Your upload is not yet associated with any record, and if you do not do anything with it, it will be deleted sometime within the next 30 minutes.) 19 | 20 | HTTP/1.0 201 OK 21 | Content-Type: application/xml 22 | 23 | 24 | 441b2cec.eve.21267 25 | 26 | Armed with the ID, your next step is to attach the file to a record. Using the "Create message" action, for instance, you pass an array of attachment data in. Assuming you had two files you wanted to attach (which you had previously uploaded, as described), your attachment data would look something like this (formatted as XML): 27 | 28 | ``` xml 29 | 30 | A pretty sunset 31 | 32 | 441b2cec.eve.21267 33 | image/jpg 34 | sunset.jpg 35 | 36 | 37 | 38 | The ocean 39 | 40 | 441b2fff.log.21285 41 | image/png 42 | ocean.png 43 | 44 | 45 | ``` 46 | -------------------------------------------------------------------------------- /sections/calendar_entries.md: -------------------------------------------------------------------------------- 1 | Calendar Entries 2 | ================ 3 | 4 | Please refer to the data reference for a full XML representation of [calendar entries](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/data_reference.md#calendar_entry) or [milestones](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/data_reference.md#milestone). 5 | 6 | Get all calendar entries 7 | ------------------------ 8 | 9 | * `GET /projects/#{project_id}/calendar_entries.xml` returns a page of calendar entries for the given project, ordered by due date. 10 | 11 | Each page contains up to 50 time entry records. To select a different page of data, set the “page” query parameter to a value greater than zero. 12 | 13 | **Response:** 14 | 15 | ``` xml 16 | 17 | 18 | ... 19 | 20 | 21 | ... 22 | 23 | ... 24 | 25 | ``` 26 | 27 | 28 | Get all milestones 29 | ------------------ 30 | 31 | * `GET /projects/#{project_id}/calendar_entries/milestones.xml` returns a list of milestones for the given project. 32 | 33 | This endpoint can return all milestones, or only those that are late, completed, or upcoming. 34 | 35 | **Request:** 36 | 37 | ``` xml 38 | 39 | 40 | #{all|late|completed|upcoming} 41 | 42 | ``` 43 | 44 | **Response:** 45 | 46 | ``` xml 47 | 48 | 49 | ... 50 | 51 | 52 | ... 53 | 54 | ... 55 | 56 | ``` 57 | 58 | 59 | Get all calendar events 60 | ----------------------- 61 | 62 | * `GET /projects/#{project_id}/calendar_entries/calendar_events.xml` returns a page of calendar events for the given project, ordered by due date. 63 | 64 | Each page contains up to 50 time entry records. To select a different page of data, set the `page` query parameter to a value greater than zero. 65 | 66 | **Response:** 67 | 68 | ``` xml 69 | 70 | 71 | ... 72 | 73 | 74 | ... 75 | 76 | ... 77 | 78 | ``` 79 | 80 | 81 | Create calendar entry 82 | --------------------- 83 | 84 | * `POST /projects/#{project_id}/calendar_entries.xml` creates a new calendar entry. 85 | 86 | To make the entry a milestone, set `type` to `Milestone`. To make a company responsible for the milestone, prefix the company id with a `c`. 87 | 88 | For `datetime`, format your entry like so: `2009-10-09T17:52:46Z` or `2009-10-09T17:52:46+00:00` 89 | 90 | **Request:** 91 | 92 | ``` xml 93 | 94 | 95 | #{title} 96 | #{start_at} 97 | #{deadline} 98 | #{Milestone|CalendarEvent} 99 | 100 | #{id} 101 | 102 | 103 | ``` 104 | 105 | **Response:** 106 | 107 | ``` xml 108 | 109 | ... 110 | 111 | ``` 112 | 113 | 114 | Update calendar entry 115 | --------------------- 116 | 117 | * `PUT /projects/#{project_id}/calendar_entries/#{id}.xml` modifies a calendar entry. 118 | 119 | Supplying a different value for `type` can convert a calendar event to a milestone and vice versa. You can use this to shift the deadline of a single milestone, and optionally shift the deadlines of subsequent milestones as well. 120 | 121 | **Request:** 122 | 123 | ``` xml 124 | 125 | 126 | #{title} 127 | #{deadline} 128 | .... 129 | 130 | 131 | #{true|false} 132 | #{true|false} 133 | 134 | ``` 135 | 136 | **Response:** 137 | 138 | ``` xml 139 | 140 | ... 141 | 142 | ``` 143 | 144 | Get calendar entry 145 | ------------------ 146 | 147 | * `GET /projects/#{project_id}/calendar_entries/#{id}.xml` returns a calendar entry identified by the given ID. 148 | 149 | **Response:** 150 | 151 | ``` xml 152 | 153 | ... 154 | 155 | ``` 156 | 157 | 158 | Destroy calendar entry 159 | ---------------------- 160 | 161 | * `DELETE /projects/#{project_id}/calendar_entries/#{id}.xml` deletes a calendar entry from the project. 162 | 163 | **Response:** 164 | 165 | Returns HTTP status code 200 on success. 166 | 167 | 168 | Complete calendar entry 169 | ----------------------- 170 | 171 | * `PUT /projects/#{project_id}/calendar_entries/#{id}/complete.xml` marks the specified milestone as complete. 172 | 173 | **Response:** 174 | 175 | ``` xml 176 | 177 | ... 178 | 179 | ``` 180 | 181 | 182 | Uncomplete calendar entry 183 | ------------------------- 184 | 185 | * `PUT /projects/#{project_id}/calendar_entries/#{id}/uncomplete.xml` marks the specified milestone as uncomplete. 186 | 187 | **Response:** 188 | 189 | ``` xml 190 | 191 | ... 192 | 193 | ``` xml 194 | -------------------------------------------------------------------------------- /sections/categories.md: -------------------------------------------------------------------------------- 1 | Categories 2 | ========== 3 | 4 | The categories API is identical for both Post categories, and Attachment categories, the only difference being the "type" parameter, which can be either "post" or "attachment". 5 | 6 | For the full XML representation of categories, [check out the data reference](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/data_reference.md#category). 7 | 8 | Get category 9 | ------------ 10 | 11 | * `GET /categories/#{id}.xml` returns a single category identified by its integer ID. 12 | 13 | **Response:** 14 | 15 | ``` xml 16 | 17 | Documents 18 | ... 19 | 20 | ``` 21 | 22 | Get categories 23 | -------------- 24 | 25 | * `GET /projects/#{project_id}/categories.xml(?type=[post|attachment])` returns all categories for the given project. 26 | 27 | To filter by type, pass the `type` parameter, which can be one of `post` or `attachment`. 28 | 29 | **Response:** 30 | 31 | ``` xml 32 | 33 | 34 | Documents 35 | ... 36 | 37 | ... 38 | 39 | ``` 40 | 41 | 42 | Create category 43 | --------------- 44 | 45 | * `POST /projects/#{project_id}/categories.xml` creates a new category of the given type for the given project. 46 | 47 | The `type` attribute is required and must be one of `post` or `attachment`. 48 | 49 | **Request:** 50 | 51 | ``` xml 52 | 53 | post 54 | Transcripts 55 | 56 | ``` 57 | 58 | 59 | **Response:** 60 | 61 | Returns HTTP status code 201 Created on success, with the Location header set to the “Get category” URL for the new category. The new category ID can be extracted from that URL. On failure, a non-200 status code will be returned, possibly with error information in XML format as the response’s content. 62 | 63 | Update category 64 | --------------- 65 | 66 | * `PUT /categories/#{id}.xml` updates an existing category identified by its integer ID. 67 | 68 | **Request:** 69 | 70 | ``` xml 71 | 72 | Transcripts 73 | 74 | ``` 75 | 76 | 77 | **Response:** 78 | 79 | Returns HTTP status code 200 on success, or any other code (and possibly error information in XML format) on error. 80 | 81 | Destroy category 82 | ---------------- 83 | 84 | * `DELETE /categories/#{id}.xml` deletes the category identified by its integer ID. 85 | 86 | Note: that only categories without elements can be deleted. 87 | 88 | Returns HTTP status code 200 on success. If the category contains elements a 409 status code (conflict) will be returned. 89 | -------------------------------------------------------------------------------- /sections/comments.md: -------------------------------------------------------------------------------- 1 | Comments 2 | ======== 3 | 4 | The comments API is identical for Messages, Milestones, Todo Items, and Calendar Events, the only difference being the resource named in URL prefix. This can be one of `posts`, `milestones`, `todo_items`, or `calendar_events`, respectively. In the documentation that follows, the generic `#{resource}` should be replaced with the resource you are acting on. 5 | 6 | For the full XML representation of comments, [check out the data reference](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/data_reference.md#comment). 7 | 8 | Get recent comments (for a commentable resource) 9 | ------------------------------------------------ 10 | 11 | * `GET /#{resource}/#{resource_id}/comments.xml` return a list of the 50 most recent comments associated with the specified resource. 12 | 13 | The resource named in the URL can be one of `posts`, `milestones`, or `todo_items`. For example, to fetch the most recent comments for the todo item with an id of 1, you would use the path: `/todo_items/1/comments.xml`. 14 | 15 | The root `` element has a `count` attribute specifying the total number of comments for the resource. If there are older comments not included in the response, the `` element will also have a `continued-at` attribute specifying the path where the next oldest 50 comments can be retrieved. 16 | 17 | **Response:** 18 | 19 | ``` xml 20 | 21 | 22 | ... 23 | 24 | 25 | ... 26 | 27 | ... 28 | 29 | ``` 30 | 31 | 32 | Get comment 33 | ----------- 34 | 35 | * `GET /comments/#{comment_id}.xml` retrieve a specific comment by its id. 36 | 37 | **Response:** 38 | 39 | ``` xml 40 | 41 | ... 42 | 43 | 44 | ``` 45 | 46 | 47 | New comment 48 | ----------- 49 | 50 | * `GET /#{resource}/#{resource_id}/comments/new.xml` returns a blank XML “template” for a single comment record, indicating which fields may be submitted to create a new comment. 51 | 52 | This endpoint will also return a custom HTTP header, `X-Create-Action` indicating where and how the data may be submitted. 53 | 54 | **Response:** 55 | 56 | ``` xml 57 | 58 | ... 59 | 60 | 61 | ``` 62 | 63 | 64 | Create comment (for a commentable resource) 65 | ------------------------------------------- 66 | 67 | * `POST /#{resource}/#{resource_id}/comments.xml` create a new comment, associating it with a specific resource. 68 | 69 | The resource named in the URL can be one of `posts`, `milestones`, or `todo_items`. For example, to create a comment for the milestone with an ID of 1, you would use the path: `/milestones/1/comments.xml`. 70 | 71 | **Request:** 72 | 73 | ``` xml 74 | 75 | #{body} 76 | 77 | ``` 78 | 79 | 80 | **Response:** 81 | 82 | Returns HTTP status code 201 Created on success, with the Location header set to the URL for the new comment. The new comment’s ID can be extracted from that URL. On failure, a non-200 status code will be returned, possibly with error information in XML format as the response’s content. 83 | 84 | 85 | Edit comment 86 | ------------ 87 | 88 | * `GET /comments/#{id}/edit.xml` returns an XML “template” for a single comment record, prefilled with the existing values for that record, and ready to be resubmitted via the “update comment” action. 89 | 90 | This endpoint will also return a custom HTTP header, `X-Update-Action`, indicating where and how the data may be submitted. 91 | 92 | **Response:** 93 | 94 | ``` xml 95 | 96 | ... 97 | 98 | 99 | ``` 100 | 101 | 102 | Update comment 103 | -------------- 104 | 105 | * `PUT /comments/#{id}.xml` update a specific comment. This can be used to edit the content of an existing comment. 106 | 107 | **Request:** 108 | 109 | ``` xml 110 | 111 | 112 | #{body} 113 | 114 | 115 | ``` 116 | 117 | **Response:** 118 | 119 | Returns HTTP status code 200 on success, or any other code (and possibly error information in XML format) on error. 120 | 121 | 122 | Destroy comment 123 | --------------- 124 | 125 | * `DELETE /comments/#{id}.xml` delete the comment with the given ID. 126 | 127 | **Response:** 128 | 129 | Returns HTTP status code 200 on success. 130 | -------------------------------------------------------------------------------- /sections/companies.md: -------------------------------------------------------------------------------- 1 | Companies 2 | ========= 3 | 4 | For the full XML representation of companies, [check out the data reference](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/data_reference.md#company). 5 | 6 | Get companies 7 | ------------- 8 | 9 | * `GET /companies.xml` returns a list of all companies visible to the requesting user. 10 | * `GET /projects/#{project_id}/companies.xml` returns a list of all companies associated with the given project. 11 | 12 | **Response:** 13 | 14 | ``` xml 15 | 16 | 17 | ... 18 | 19 | 20 | ... 21 | 22 | ... 23 | 24 | ``` 25 | 26 | 27 | Get company 28 | ----------- 29 | 30 | * `GET /companies/#{company_id}.xml` returns a single company identified by its integer ID. 31 | 32 | **Response:** 33 | 34 | ``` xml 35 | 36 | 1 37 | Globex Corporation 38 | 39 | ``` 40 | -------------------------------------------------------------------------------- /sections/data_reference.md: -------------------------------------------------------------------------------- 1 | Data Reference 2 | ============== 3 | 4 | Account 5 | ------- 6 | 7 | ``` xml 8 | 9 | 1 10 | Your Company 11 | 1 12 | true 13 | true 14 | true 15 | 2009-10-09T17:52:46Z 16 | 17 | Premium 18 | Infinity 19 | 100 20 | 32212254720 21 | true 22 | true 23 | 24 | 25 | Documents 26 | Pictures 27 | Sounds 28 | 29 | 30 | Design 31 | Code 32 | Copywriting 33 | Transcripts 34 | Assets 35 | Miscellaneous 36 | 37 | 38 | ``` 39 | 40 | Attachment 41 | ---------- 42 | 43 | ``` xml 44 | 45 | #{id} 46 | #{name} 47 | #{description} 48 | #{byte_size} 49 | #{download_url} 50 | 51 | #{project_id} 52 | #{category_id} 53 | #{person_id} 54 | #{private} 55 | #{created_on} 56 | 57 | 58 | #{owner_id} 59 | #{owner_type} 60 | 61 | 64 | #{collection} 65 | #{version} 66 | #{current} 67 | 68 | ``` 69 | 70 | Calendar entry 71 | -------------- 72 | 73 | ``` xml 74 | 75 | #{id} 76 | #{title} 77 | #{Milestone|CalendarEvent} 78 | #{start_at} 79 | #{deadline} 80 | #{project_id} 81 | #{created_on} 82 | #{creator_id} 83 | #{creator_name} 84 | #{commented_at} 85 | #{comments_count} 86 | 87 | 88 | #{true|false} 89 | #{responsible_party_id} 90 | #{responsible_party_type} 91 | #{responsible_party_name} 92 | 93 | 94 | #{completed_on} 95 | #{completer_id} 96 | #{completer_name} 97 | 98 | ``` 99 | 100 | Category 101 | -------- 102 | 103 | ``` xml 104 | 105 | #{id} 106 | #{name} 107 | #{project_id} 108 | #{elements_count} 109 | #{type} 110 | 111 | ``` 112 | 113 | Comment 114 | ------- 115 | 116 | ``` xml 117 | 118 | #{id} 119 | #{author_id} 120 | #{author_name} 121 | #{commentable_id} 122 | #{commentable_type} 123 | #{body} 124 | #{emailed_from} 125 | #{created_at} 126 | 127 | #{attachments_count} 128 | 129 | 130 | ... 131 | 132 | ... 133 | 134 | 135 | ``` 136 | 137 | Company 138 | ------- 139 | 140 | ``` xml 141 | 142 | #{id} 143 | #{name} 144 | #{address_one} 145 | #{address_two} 146 | #{city} 147 | #{state} 148 | #{zip} 149 | #{country} 150 | #{web_address} 151 | #{phone_number_office> 152 | #{phone_number_fax} 153 | #{time_zone_id} 154 | #{can_see_private} 155 | 156 | 157 | #{url_name} 158 | 159 | ``` 160 | 161 | Milestone 162 | --------- 163 | 164 | ``` xml 165 | 166 | #{id} 167 | #{title} 168 | #{deadline} 169 | #{true|false} 170 | #{project_id} 171 | #{created_on} 172 | #{creator_id} 173 | #{creator_name} 174 | #{responsible_party_id} 175 | #{responsible_party_type} 176 | #{responsible_party_name} 177 | #{commented_at} 178 | #{comments_count} 179 | 180 | 181 | #{completed_at} 182 | #{completer_id} 183 | #{completer_name} 184 | 185 | ``` 186 | 187 | Person 188 | ------ 189 | 190 | ``` xml 191 | 192 | #{id} 193 | #{first_name} 194 | #{last_name} 195 | #{title} 196 | #{email_address} 197 | #{im_handle} 198 | #{im_service} 199 | #{phone_number_office} 200 | #{phone_number_office_ext} 201 | #{phone_number_mobile} 202 | #{phone_number_home} 203 | #{phone_number_fax} 204 | #{company_id} 205 | #{client_id} 206 | #{time_zone_name} 207 | 208 | #{avatar_url} 209 | 210 | 211 | #{user_name} 212 | 213 | 214 | #{administrator} 215 | #{deleted} 216 | #{has_access_to_new_projects} 217 | 218 | ``` 219 | 220 | Post 221 | ---- 222 | 223 | ``` xml 224 | 225 | #{id} 226 | #{title} 227 | #{body} 228 | #{display_body} 229 | #{posted_on} 230 | #{commented_at} 231 | #{project_id} 232 | #{category_id} 233 | #{author_id} 234 | #{author_name} 235 | #{milestone_id} 236 | #{comments_count} 237 | #{use_textile} 238 | #{extended_body} 239 | #{display_extended_body} 240 | 241 | #{attachments_count} 242 | 243 | 244 | ... 245 | 246 | ... 247 | 248 | 249 | 250 | #{private} 251 | 252 | ``` 253 | 254 | Post (Abbreviated) 255 | ------------------ 256 | 257 | ``` xml 258 | 259 | #{id} 260 | #{title} 261 | #{author_name} 262 | #{posted_on} 263 | #{commented_at} 264 | #{attachments_count} 265 | 266 | #{id} 267 | #{name} 268 | 269 | 270 | ``` 271 | 272 | Project 273 | ------- 274 | 275 | ``` xml 276 | 277 | #{id} 278 | #{name} 279 | #{created_on} 280 | #{status} 281 | #{last_changed_on} 282 | 283 | #{id} 284 | #{name} 285 | 286 | 287 | 288 | #{announcement} 289 | 290 | 291 | #{start_page} 292 | #{show_writeboards} 293 | #{show_announcement} 294 | 295 | ``` 296 | 297 | Subscription 298 | ------------ 299 | 300 | ``` xml 301 | 302 | Premium 303 | Infinity 304 | 100 305 | 32212254720 306 | true 307 | true 308 | 309 | ``` 310 | 311 | Time entry 312 | ---------- 313 | 314 | ``` xml 315 | 316 | #{id} 317 | #{project_id} 318 | #{person_id} 319 | #{person_name} 320 | #{date} 321 | #{hours} 322 | #{description} 323 | #{todo_item_id} 324 | 325 | ``` 326 | 327 | Todo item 328 | --------- 329 | 330 | ``` xml 331 | 332 | #{id} 333 | #{todo_list_id} 334 | #{content} 335 | #{position} 336 | #{created_on} 337 | #{creator_id} 338 | #{creator_name} 339 | #{completed} 340 | #{updated_at} 341 | #{commented_at} 342 | #{comments_count} 343 | 344 | 345 | #{due_at} 346 | 347 | 348 | #{responsible_party_type} 349 | #{responsible_party_id} 350 | #{responsible_party_name} 351 | 352 | 353 | #{completed_at} 354 | #{completer_id} 355 | #{completer_name} 356 | 357 | ``` 358 | 359 | Todo list 360 | --------- 361 | 362 | ``` xml 363 | 364 | #{id} 365 | #{name} 366 | #{description} 367 | #{project_id} 368 | #{milestone_id} 369 | #{position} 370 | #{completed} 371 | 372 | 373 | #{private} 374 | 375 | 376 | #{tracked} 377 | 378 | 379 | 380 | 381 | ... 382 | 383 | 384 | ... 385 | 386 | ... 387 | 388 | 389 | ``` 390 | -------------------------------------------------------------------------------- /sections/files.md: -------------------------------------------------------------------------------- 1 | Files 2 | ===== 3 | 4 | For the full XML representation of files, [check out the data reference](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/data_reference.md#attachment). 5 | 6 | Get files 7 | --------- 8 | 9 | * `GET /projects/#{project_id}/attachments.xml(?n=...)` returns a list of files (attachments) in the given project that are visible to the authenticated user. 10 | 11 | The list is paginated using offsets. If 100 attachments are returned (the page limit), use `?n=100` to check for the next 100 and so on. 12 | 13 | **Response:** 14 | 15 | ``` xml 16 | 17 | 18 | ... 19 | 20 | 21 | ... 22 | 23 | ... 24 | 25 | ``` 26 | -------------------------------------------------------------------------------- /sections/messages.md: -------------------------------------------------------------------------------- 1 | Messages 2 | ======== 3 | 4 | The Messages API names its resource "posts", not "messages". 5 | 6 | For the full XML representation of messages, [check out the data reference](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/data_reference.md#message). 7 | 8 | Get messages 9 | ------------ 10 | 11 | * `GET /projects/#{project_id}/posts.xml` returns the 25 most recent messages in the given project. 12 | * `GET /projects/#{project_id}/cat/#{category_id}/posts.xml` returns the most 25 most recent messages in the given project for the given category. 13 | 14 | Messages are paginated using offsets. If 25 elements are returned (the page limit), use `?n=25` to fetch the next 25, and so on. 15 | 16 | **Response:** 17 | 18 | ``` xml 19 | 20 | 21 | ... 22 | 23 | ... 24 | 25 | 26 | ``` 27 | 28 | 29 | Get message 30 | ----------- 31 | 32 | * `GET /posts/#{id}.xml` returns a single message record identified by its integer ID. 33 | 34 | **Response:** 35 | 36 | ``` xml 37 | 38 | ... 39 | 40 | 41 | ``` 42 | 43 | 44 | Get archived messages 45 | --------------------- 46 | 47 | * `GET /projects/#{project_id}/posts/archive.xml` returns a summary record for each message in the given project. 48 | * `GET /projects/#{project_id}/cat/#{category_id}/posts/archive.xml` returns a summary record for each message in the given project for the given category. 49 | 50 | Note: that a summary record includes only a few bits of information about a message, not the complete record. 51 | 52 | **Response:** 53 | 54 | ``` xml 55 | 56 | 57 | ... 58 | 59 | 60 | ... 61 | 62 | ... 63 | 64 | ``` 65 | 66 | 67 | New message 68 | ----------- 69 | 70 | * `GET /projects/#{project_id}/posts/new.xml` returns a blank XML “template” for a single message record, indicating which fields may be submitted to create a new message. 71 | 72 | This endpoint will also return a custom HTTP header, `X-Create-Action` indicating where and how the data may be submitted. 73 | 74 | **Response:** 75 | 76 | ``` xml 77 | 78 | ... 79 | 80 | 81 | ``` 82 | 83 | 84 | Create message 85 | -------------- 86 | 87 | * `POST /projects/#{project_id}/posts.xml` creates a new message, optionally sending notifications to a selected list of people. 88 | 89 | Note: you can also upload files using this function, but you need to upload the files first and then attach them. 90 | 91 | **Request:** 92 | 93 | ``` xml 94 | 95 | 96 | #{category_id} 97 | #{title} 98 | #{body} 99 | 1 100 | 101 | #{person_id} 102 | #{person_id} 103 | ... 104 | 105 | #{name} 106 | 107 | #{temp_id} 108 | #{content_type} 109 | #{original_filename} 110 | 111 | 112 | ... 113 | ... 114 | 115 | ``` 116 | 117 | 118 | **Response:** 119 | 120 | Returns HTTP status code 201 Created on success, with the Location header set to the “Get message” URL for the new message. The new message ID can be extracted from that URL. On failure, a non-200 status code will be returned, possibly with error information in XML format as the response’s content. 121 | 122 | Edit message 123 | ------------ 124 | 125 | * `GET /posts/#{id}/edit.xml` returns an XML “template” for a single message record, prefilled with the existing values for that record, and ready to be resubmitted via the “update message” action. 126 | 127 | This endpoint will also return a custom HTTP header, `X-Update-Action` indicating where and how the data may be submitted. 128 | 129 | **Response:** 130 | 131 | ``` xml 132 | 133 | ... 134 | 135 | 136 | ``` 137 | 138 | 139 | Update message 140 | -------------- 141 | 142 | * `PUT /posts/#{id}.xml` updates an existing message, optionally sending notifications to a selected list of people. 143 | 144 | Note: you can also upload files using this function, but you need to upload the files first and then attach them. 145 | 146 | **Request:** 147 | 148 | ``` xml 149 | 150 | 151 | #{category_id} 152 | #{title} 153 | #{body} 154 | 1 155 | 1 156 | 157 | #{person_id} 158 | #{person_id} 159 | ... 160 | 161 | ``` 162 | 163 | 164 | **Response:** 165 | 166 | Returns HTTP status code 200 on success, or any other code (and possibly error information in XML format) on error. 167 | 168 | 169 | Destroy message 170 | --------------- 171 | 172 | * `DELETE /posts/#{id}.xml` destroys the given message and all of its associated comments. 173 | 174 | Returns HTTP status code 200 on success. 175 | -------------------------------------------------------------------------------- /sections/people.md: -------------------------------------------------------------------------------- 1 | People 2 | ====== 3 | 4 | For the full XML representation of people, [check out the data reference](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/data_reference.md#person). 5 | 6 | Current person 7 | -------------- 8 | 9 | * `GET /me.xml` returns the currently logged in person (you). 10 | 11 | **Response:** 12 | 13 | ``` xml 14 | 15 | #{id} 16 | #{user_name} 17 | ... 18 | 19 | ``` 20 | 21 | 22 | Get people (across projects) 23 | ---------------------------- 24 | 25 | Admins can include deleted people using the `?include_deleted=true` query parameter. 26 | 27 | * `GET /people.xml` returns all people visible to (and including) the requesting user. 28 | * `GET /projects/#{project_id}/people.xml` returns all people with access to the given project. 29 | * `GET /companies/#{company_id}/people.xml` returns all people from the given company that are visible to the requesting user. 30 | 31 | **Response:** 32 | 33 | ``` xml 34 | 35 | 36 | ... 37 | 38 | ... 39 | 40 | ``` 41 | 42 | 43 | Get person 44 | ---------- 45 | 46 | * `GET /people/#{person_id}.xml` returns a single person identified by their integer ID. 47 | 48 | **Response:** 49 | 50 | ``` xml 51 | 52 | ... 53 | 54 | ``` 55 | -------------------------------------------------------------------------------- /sections/projects.md: -------------------------------------------------------------------------------- 1 | Projects 2 | ======== 3 | 4 | For the full XML representation of projects, [check out the data reference](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/data_reference.md#project). 5 | 6 | Get projects 7 | ------------ 8 | 9 | * `GET /projects.xml` returns all accessible projects. This includes active, inactive, and archived projects. 10 | 11 | **Response:** 12 | 13 | ``` xml 14 | 15 | 16 | ... 17 | 18 | 19 | ... 20 | 21 | ... 22 | 23 | 24 | ``` 25 | 26 | 27 | Get project 28 | ----------- 29 | 30 | * `GET /projects/#{project_id}.xml` returns a single project identified by its integer ID 31 | 32 | **Response:** 33 | 34 | ``` xml 35 | 36 | Design Review 37 | ... 38 | 39 | Globex Corporation 40 | ... 41 | 42 | 43 | 44 | ``` 45 | 46 | 47 | Create project 48 | -------------- 49 | 50 | * `POST /projects.xml` creates a new project with the given name. 51 | 52 | **Request:** 53 | 54 | ``` xml 55 | 56 | 57 | Shopping Cart Redesign 58 | 59 | 60 | ``` 61 | 62 | 63 | **Response:** 64 | 65 | Returns status code 201 (Created) on success with the Location header set to the URL for the new project. You can extract the ID of the project from the URL. Failed requests will receive a 422 (Unprocessable Entity) or 500 (Server Error) status code in the response. 66 | 67 | 68 | Update project 69 | -------------- 70 | 71 | * `PUT /projects/#{project_id}.xml` updates attributes of the given project. 72 | 73 | Only administrative users may update project records. You only need to provide the attributes you wish to update; others ought to be omitted from the request. 74 | 75 | **Request:** 76 | 77 | ``` xml 78 | 79 | Shopping Cart Redesign 80 | log|all|todos|milestones|files 81 | active|on_hold|archived 82 | #{client-id} 83 | true|false 84 | ... 85 | true|false 86 | 87 | ``` 88 | 89 | 90 | **Response:** 91 | 92 | Returns 200 OK on success. Otherwise, returns an error code (e.g. 422 or 403), possibly including a payload describing the error. 93 | 94 | 95 | Project counts 96 | -------------- 97 | 98 | * `GET /projects/count.xml` returns a count of all projects, by project status. 99 | 100 | If there are no projects with a particular status, that status entry will be omitted from the report. 101 | 102 | **Response:** 103 | 104 | ``` xml 105 | 106 | 5 107 | 2 108 | 11 109 | 110 | ``` 111 | -------------------------------------------------------------------------------- /sections/time_tracking.md: -------------------------------------------------------------------------------- 1 | Time tracking 2 | ============= 3 | 4 | For the full XML representation of time entries, [check out the data reference](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/data_reference.md#time_entry). 5 | 6 | Get all entries 7 | --------------- 8 | 9 | * `GET /todo_items/#{todo_item_id}/time_entries.xml` returns all time entries associated with the given todo item, in descending order by date. 10 | * `GET /projects/#{project_id}/time_entries.xml` returns a page full of time entries for the given project, in descending order by date. 11 | 12 | For the project time entries request, each page contains up to 50 time entry records. To select a specific page, set the `page` query parameter to 1 or larger. The `X-Records` HTTP header will be set to the total number of time entries in the project, `X-Pages` will be set to the total number of pages, and `X-Page` will be set to the current page. 13 | 14 | **Response:** 15 | 16 | ``` xml 17 | 18 | 19 | ... 20 | 21 | ... 22 | 23 | ``` 24 | 25 | 26 | Create entry 27 | ------------ 28 | 29 | * `POST /projects/#{project_id}/time_entries.xml` creates a new time entry for the given project. 30 | * `POST /todo_items/#{todo_item_id}/time_entries.xml` creates a new time entry for the given todo item. 31 | 32 | **Request:** 33 | 34 | ``` xml 35 | 36 | #{person-id} 37 | #{date} 38 | #{hours} 39 | #{description} 40 | 41 | ``` 42 | 43 | **Response:** 44 | 45 | Returns HTTP status code 201 Created on success, with the Location header set to the URL of the new time entry. The integer ID of the entry may be extracted from that URL. 46 | 47 | 48 | New entry 49 | --------- 50 | 51 | * `GET /projects/#{project_id}/time_entries/new.xml` returns a blank “template” XML record for defining a new time entry. 52 | 53 | Simply modify the fields accordingly, and submit as described by the `X-Create-Action` HTTP header. 54 | 55 | **Response:** 56 | 57 | ``` xml 58 | 59 | ... 60 | 61 | ``` 62 | 63 | 64 | Get entry 65 | --------- 66 | 67 | * `GET /time_entries/#{id}.xml` retrieves a single time-entry record, given its integer ID. 68 | 69 | **Response:** 70 | 71 | ``` xml 72 | 73 | ... 74 | 75 | ``` 76 | 77 | 78 | Edit entry 79 | ---------- 80 | 81 | * `GET /time_entries/#{id}/edit.xml` returns the requested time-entry record, but only those fields that may be edited. 82 | 83 | Simply modify the fields and submit as described by the `X-Update-Action` HTTP header. 84 | 85 | **Response:** 86 | 87 | ``` xml 88 | 89 | ... 90 | 91 | ``` 92 | 93 | 94 | Update entry 95 | ------------ 96 | 97 | * `PUT /time_entries/#{id}.xml` updates the given time-entry record with the data given. 98 | 99 | **Request:** 100 | 101 | ``` xml 102 | 103 | #{person-id} 104 | #{date} 105 | #{hours} 106 | #{description} 107 | 108 | 109 | #{todo-item-id} 110 | 111 | ``` 112 | 113 | **Response:** 114 | 115 | Returns HTTP status code 200 on success. 116 | 117 | 118 | Destroy entry 119 | ------------- 120 | 121 | * `DELETE /time_entries/#{id}.xml` destroys the given time entry record. 122 | 123 | **Response:** 124 | 125 | Returns HTTP status code 200 on success. 126 | 127 | 128 | Get report 129 | ---------- 130 | 131 | * `GET /time_entries/report.xml` return the set of time entries that match the given criteria. 132 | 133 | This action accepts the following query parameters: `from`, `to`, `subject_id`, `todo_item_id`, `filter_project_id`, and `filter_company_id`. Both `from` and `to` should be dates in `YYYYMMDD` format, and can be used to restrict the result to a particular date range. (No more than 6 months’ worth of entries may be returned in a single query, though). The `subject_id` parameter lets you constrain the result to a single person’s time entries. `todo_item_id` restricts the result to only those entries relating to the given todo item. `filter_project_id` restricts the entries to those for the given project, and `filter_company_id` restricts the entries to those for the given company. 134 | 135 | **Response:** 136 | 137 | ``` xml 138 | 139 | 140 | ... 141 | 142 | ... 143 | 144 | ``` 145 | -------------------------------------------------------------------------------- /sections/todo_list_items.md: -------------------------------------------------------------------------------- 1 | Todo List Items 2 | =============== 3 | 4 | For the full XML representation of todo items, [check out the data reference](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/data_reference.md#todo_item). 5 | 6 | Get all items (for a list) 7 | -------------------------- 8 | 9 | * `GET /todo_lists/#{todo_list_id}/todo_items.xml` returns all todo item records for a single todo list. 10 | 11 | This is almost the same as the “Get list” action, except it does not return any information about the list itself. The items are returned in priority order, as defined by how they were ordered either in the web UI, or via the “Reorder items” action. 12 | 13 | **Response:** 14 | 15 | ``` xml 16 | 17 | 18 | ... 19 | 20 | ... 21 | 22 | ``` 23 | 24 | 25 | Get item 26 | -------- 27 | 28 | * `GET /todo_items/#{id}.xml` returns a single todo item record, given its integer ID. 29 | 30 | **Response:** 31 | 32 | ``` xml 33 | 34 | ... 35 | 36 | ``` 37 | 38 | 39 | Complete item 40 | ------------- 41 | 42 | * `PUT /todo_items/#{id}/complete.xml` marks the specified todo item as completed. 43 | 44 | **Response:** 45 | 46 | Returns HTTP status code 200 on success. 47 | 48 | 49 | Uncomplete item 50 | --------------- 51 | 52 | * `PUT /todo_items/#{id}/uncomplete.xml` marks the specified todo as uncompleted. 53 | 54 | If the specified todo item was previously marked as completed, this unmarks it, restoring it to an “uncompleted” state. If it was already in the uncompleted state, this call has no effect. 55 | 56 | **Response:** 57 | 58 | Returns HTTP status code 200 on success. 59 | 60 | 61 | New item 62 | -------- 63 | 64 | * `GET /todo_lists/#{todo_list_id}/todo_items/new.xml` returns a “blank” XML record that may be used as a template for creating a new todo item. 65 | 66 | Just fill in the fields and submit the data as indicated by the custom X-Create-Action HTTP header. 67 | 68 | **Response:** 69 | 70 | ``` xml 71 | 72 | ... 73 | 74 | ``` 75 | 76 | 77 | Create item 78 | ----------- 79 | 80 | * `POST /todo_lists/#{todo_list_id}/todo_items.xml` creates a new todo item record for the given list. 81 | 82 | The new record begins its life in the `uncompleted` state. (See the “Complete” and “Uncomplete” actions.) It is added at the bottom of the given list. If a person is responsible for the item, give their id as the party_id value. If a company is responsible, prefix their company id with a ‘c’ and use that as the party_id value. If the item has a person as the responsible party, you can also use the `notify` key to indicate whether an email should be sent to that person to tell them about the assignment. 83 | 84 | **Request:** 85 | 86 | ``` xml 87 | 88 | #{content} 89 | 90 | 91 | #{due_at} 92 | 93 | 94 | #{party_id} 95 | #{true|false} 96 | 97 | ``` 98 | 99 | **Response:** 100 | 101 | Returns HTTP status code 201 Created on success, with the Location header being set to the URL for the new item. (The new item’s integer ID may be extractd from that URL.) 102 | 103 | 104 | Update item 105 | ----------- 106 | 107 | * `PUT /todo_items/#{id}.xml` updates an existing todo item record with the given data. 108 | 109 | See the “Create item” action for a full discussion of the meaning of the data fields. 110 | 111 | **Request:** 112 | 113 | ``` xml 114 | 115 | #{content} 116 | 117 | 118 | #{party_id} 119 | #{true|false} 120 | 121 | ``` 122 | 123 | **Response:** 124 | 125 | Returns HTTP status code 200 on success. 126 | 127 | 128 | Edit item 129 | --------- 130 | 131 | * `GET /todo_items/#{id}/edit.xml` returns an XML record for the requested todo item, ready to be modified and submitted via the “Update item” action. 132 | 133 | A custom HTTP header, `X-Update-Action`, is also given, indicating where and how the data may be submitted. 134 | 135 | **Response:** 136 | 137 | ``` xml 138 | 139 | ... 140 | 141 | ``` 142 | 143 | 144 | Destroy item 145 | ------------ 146 | 147 | * `DELETE /todo_items/#{id}.xml` destroys the given todo item record. 148 | 149 | **Response:** 150 | 151 | Returns HTTP status code 200 on success. 152 | 153 | 154 | Reorder items 155 | ------------- 156 | 157 | * `POST /todo_lists/#{todo_list_id}/todo_items/reorder.xml` changes the ordering of the items for the given list. 158 | 159 | Completed items cannot be reordered, and any items not specified will be sorted after the items explicitly given (allowing you to easily move a single item to the head of the list without having to specify the positions of all the other items). You may reparent items by putting items from one list into the ordering of items for a different list (though items cannot be reparented across project boundaries). 160 | 161 | **Request:** 162 | 163 | ``` xml 164 | 165 | #{id} 166 | ... 167 | 168 | ``` 169 | 170 | **Response:** 171 | 172 | Returns HTTP status code 200 on success. 173 | -------------------------------------------------------------------------------- /sections/todo_lists.md: -------------------------------------------------------------------------------- 1 | Todo lists 2 | ========== 3 | 4 | Please refer to the data reference for a full XML representation of [todo lists](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/data_reference.md#todo_list) or [todo items](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/data_reference.md#todo_item). 5 | 6 | Get all lists (across projects) 7 | ------------------------------- 8 | 9 | * `GET /todo_lists.xml` returns a list of todo-list records for the current user, with todo-item records assigned to the current user 10 | * `GET /todo_lists.xml?responsible_party=#{id}` returns a list of todo-list records, with todo-item records that are assigned to the given `responsible party`. 11 | 12 | The responsible party may be changed by setting the `responsible_party` query parameter to a blank string (for unassigned items), a person-id, or a company-id prefixed by a `c` (e.g., `c1234`). 13 | 14 | **Response:** 15 | 16 | ``` xml 17 | 18 | 19 | ... 20 | 21 | 22 | ... 23 | 24 | 25 | 26 | ... 27 | 28 | 29 | ``` 30 | 31 | 32 | Get all lists (within project) 33 | ------------------------------ 34 | 35 | * `GET /projects/#{project_id}/todo_lists.xml?filter=#{filter}` returns a list of todo-list records that are in the given project. 36 | 37 | By default, all lists are returned, but you can filter the result by giving the `filter` query parameter, set to `all` (the default), `pending` (for lists with uncompleted items), and `finished` (for lists that have no uncompleted items). The lists will be returned in priority order, as determined by their ordering. 38 | 39 | **Response:** 40 | 41 | ``` xml 42 | 43 | 44 | ... 45 | 46 | ... 47 | 48 | ``` 49 | 50 | 51 | Get list 52 | -------- 53 | 54 | * `GET /todo_lists/#{id}.xml` returns a single todo-list record identified by its integer ID. 55 | 56 | **Response:** 57 | 58 | ``` xml 59 | 60 | ... 61 | 62 | 63 | ``` 64 | 65 | 66 | Edit list 67 | --------- 68 | 69 | * `GET /todo_lists/#{id}/edit.xml` returns an XML “template” for a single todo-list record, prefilled with the existing values for that record, and ready to be resubmitted via the “update list” action. 70 | 71 | This endpoint will also return a custom HTTP header, `X-Update-Action`, indicating where and how the data may be submitted. 72 | 73 | **Response:** 74 | 75 | ``` xml 76 | 77 | ... 78 | 79 | 80 | ``` 81 | 82 | 83 | Update list 84 | ----------- 85 | 86 | * `PUT /todo_lists/#{id}.xml` updates the specified todo-list record with the changes indicated by the submitted XML data. 87 | 88 | **Request:** 89 | 90 | ``` xml 91 | 92 | #{name} 93 | #{description} 94 | #{milestone_id} 95 | #{true|false} 96 | #{true|false} 97 | 98 | ``` 99 | 100 | **Response:** 101 | 102 | Returns HTTP status code 200 on success, or any other code (and possibly error information in XML format) on error. 103 | 104 | 105 | New list 106 | -------- 107 | 108 | * `GET /projects/#{project_id}/todo_lists/new.xml` returns a blank XML “template” for a single todo-list record, indicating which fields may be submitted to create a new list. 109 | 110 | This endpoint will also return a custom HTTP header, `X-Create-Action`, indicating where and how the data may be submitted. 111 | 112 | **Response:** 113 | 114 | ``` xml 115 | 116 | ... 117 | 118 | ``` 119 | 120 | 121 | Create list 122 | ----------- 123 | 124 | * `POST /projects/#{project_id}/todo_lists.xml` creates a new todo-list based on the submitted XML data. 125 | 126 | If you wish to base the new list on a todo-list template that you’ve created previously, you can specify the `todo-list-template-id` field in the data, and the new list will default to the name, description, and todo-items indicated by that template. 127 | 128 | **Request:** 129 | 130 | ``` xml 131 | 132 | #{name} 133 | #{description} 134 | #{milestone_id} 135 | #{true|false} 136 | #{true|false} 137 | 138 | 139 | #{template_id} 140 | 141 | ``` 142 | 143 | **Response:** 144 | 145 | Returns HTTP status code 201 Created on success, with the Location header set to the “Get list” URL for the new list. The new list’s ID can be extracted from that URL. On failure, a non-200 status code will be returned, possibly with error information in XML format as the response’s content. 146 | 147 | 148 | Destroy list 149 | ------------ 150 | 151 | * `DELETE /todo_lists/#{id}.xml` destroys the given todo-list and all of its associated todo items. 152 | 153 | **Response:** 154 | 155 | Returns HTTP status code 200 on success. 156 | 157 | 158 | Reorder lists 159 | ------------- 160 | 161 | * `POST /projects/#{project_id}/todo_lists/reorder.xml` reorders the lists in the project according to the ordering given. 162 | 163 | Any lists that are not explicitly specified will be positioned after the lists that are specified. 164 | 165 | **Request:** 166 | 167 | ``` xml 168 | 169 | ... 170 | ... 171 | ... 172 | 173 | ``` 174 | 175 | **Response:** 176 | 177 | Returns HTTP status code 200 on success. 178 | --------------------------------------------------------------------------------