├── 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 |
--------------------------------------------------------------------------------