├── 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 '<todo-item><content>...</content></todo-item>' \
 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 | <account>
22 |   <id type="integer">1</id>
23 |   <name>Your Company</name>
24 |   <account-holder-id type="integer">1</account-holder-id>
25 |   <primary-company-id type="integer">1</primary-company-id>
26 |   <ssl-enabled type="boolean">true</ssl-enabled>
27 |   <email-notification-enabled type="boolean">true</email-notification-enabled>
28 |   <time-tracking-enabled type="boolean">true</time-tracking-enabled>
29 |   <updated-at type="datetime">2009-10-09T17:52:46Z</updated-atcription>
30 |   <subscription>
31 |     <name>Premium</name>
32 |     <writeboards type="float">Infinity</writeboards>
33 |     <projects type="integer">100</projects>
34 |     <storage type="integer">32212254720</storage>
35 |     <ssl type="boolean">true</ssl>
36 |     <time-tracking type="boolean">true</time-tracking>
37 |   </subscription>
38 |   <default-attachment-categories>
39 |     <category>Documents</category>
40 |     <category>Pictures</category>
41 |     <category>Sounds</category>
42 |   </default-attachment-categories>
43 |   <default-post-categories>
44 |     <category>Design</category>
45 |     <category>Code</category>
46 |     <category>Copywriting</category>
47 |     <category>Transcripts</category>
48 |     <category>Assets</category>
49 |     <category>Miscellaneous</category>
50 |   </default-post-categories>
51 | </account>
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 |     <?xml version="1.0" encoding="UTF-8"?>
24 |     <upload><id>441b2cec.eve.21267</id></upload>
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 | <attachments>
30 |   <name>A pretty sunset</name>
31 |   <file>
32 |     <file>441b2cec.eve.21267</file>
33 |     <content-type>image/jpg</content-type>
34 |     <original-filename>sunset.jpg</original-filename>
35 |   </file>
36 | </attachments>
37 | <attachments>
38 |   <name>The ocean</name>
39 |   <file>
40 |     <file>441b2fff.log.21285</file>
41 |     <content-type>image/png</content-type>
42 |     <original-filename>ocean.png</original-filename>
43 |   </file>
44 | </attachments>
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 | <calendar-entries>
 17 |   <calendar-entry>
 18 |     ...
 19 |   </calendar-entry>
 20 |   <calendar-entry>
 21 |     ...
 22 |   </calendar-entry>
 23 |   ...
 24 | </calendar-entries>
 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 | <request>
 39 |   <!-- optional, defaults to all -->
 40 |   <find>#{all|late|completed|upcoming}</find>
 41 | </request>
 42 | ```
 43 | 
 44 | **Response:**
 45 | 
 46 | ``` xml
 47 | <calendar-entries>
 48 |   <calendar-entry>
 49 |     ...
 50 |   </calendar-entry>
 51 |   <calendar-entry>
 52 |     ...
 53 |   </calendar-entry>
 54 |   ...
 55 | </calendar-entries>
 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 | <calendar-entries>
 70 |   <calendar-entry>
 71 |     ...
 72 |   </calendar-entry>
 73 |   <calendar-entry>
 74 |     ...
 75 |   </calendar-entry>
 76 |   ...
 77 | </calendar-entries>
 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 | <request>
 94 |   <calendar-entry>
 95 |     <title>#{title}</title>
 96 |     <start-at type="date">#{start_at}</start-at>
 97 |     <deadline type="{date|datetime}">#{deadline}</deadline>
 98 |     <type>#{Milestone|CalendarEvent}</type>
 99 |     <!-- Only applicable to milestones -->
100 |     <responsible-party>#{id}</responsible-party>
101 |   </calendar-entry>
102 | </request>
103 | ```
104 | 
105 | **Response:**
106 | 
107 | ``` xml
108 | <calendar-entry>
109 |   ...
110 | </calendar-entry>
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 | <request>
125 |   <calendar-entry>
126 |     <title>#{title}</title>
127 |     <deadline>#{deadline}</deadline>
128 |     ....
129 |   </calendar-entry>
130 |   <!-- Only applicable to milestones -->
131 |   <move-upcoming-milestones>#{true|false}</move-upcoming-milestones>
132 |   <move-upcoming-milestones-off-weekends>#{true|false}</move-upcoming-milestones-off-weekends>
133 | </request>
134 | ```
135 | 
136 | **Response:**
137 | 
138 | ``` xml
139 | <calendar-entry>
140 |   ...
141 | </calendar-entry>
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 | <calendar-entry>
153 |   ...
154 | </calendar-entry>
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 | <calendar-entry>
177 |   ...
178 | </calendar-entry>
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 | <calendar-entry>
191 |   ...
192 | </calendar-entry>
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 | <category>
17 |   <name>Documents</name>
18 |   ...
19 | <category>
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 | <categories>
33 |   <category>
34 |     <name>Documents</name>
35 |     ...
36 |   </category>
37 |   ...
38 | </categories>
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 | <category>
53 |   <type>post</type>
54 |   <name>Transcripts</name>
55 | </category>
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 | <category>
72 |   <name>Transcripts</name>
73 | </category>
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 `<comments>` 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 `<comments>` 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 | <comments count="50" continued-at="...">
 21 |   <comment>
 22 |     ...
 23 |   </comment>
 24 |   <comment>
 25 |     ...
 26 |   </comment>
 27 |   ...
 28 | </comments>
 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 | <comment>
 41 |   ...
 42 | </comment>
 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 | <comment>
 58 |   ...
 59 | </comment>
 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 | <comment>
 75 |   <body>#{body}</body>
 76 | </comment>
 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 | <comment>
 96 |   ...
 97 | </comment>
 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 | <request>
111 |   <comment>
112 |     <body>#{body}</body>
113 |   </comment>
114 | </request>
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 | <companies>
16 |   <company>
17 |     ...
18 |   </company>
19 |   <company>
20 |     ...
21 |   </company>
22 |   ...
23 | </company>
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 | <company>
36 |   <id type="integer">1</id>
37 |   <name>Globex Corporation</name>
38 | </company>
39 | ```
40 | 


--------------------------------------------------------------------------------
/sections/data_reference.md:
--------------------------------------------------------------------------------
  1 | Data Reference
  2 | ==============
  3 | 
  4 | Account
  5 | -------
  6 | 
  7 | ``` xml
  8 | <account>
  9 |   <id type="integer">1</id>
 10 |   <name>Your Company</name>
 11 |   <account-holder-id type="integer">1</account-holder-id>
 12 |   <ssl-enabled type="boolean">true</ssl-enabled>
 13 |   <email-notification-enabled type="boolean">true</email-notification-enabled>
 14 |   <time-tracking-enabled type="boolean">true</time-tracking-enabled>
 15 |   <updated-at type="datetime">2009-10-09T17:52:46Z</updated-at>
 16 |   <subscription>
 17 |     <name>Premium</name>
 18 |     <writeboards type="float">Infinity</writeboards>
 19 |     <projects type="integer">100</projects>
 20 |     <storage type="integer">32212254720</storage>
 21 |     <ssl type="boolean">true</ssl>
 22 |     <time-tracking type="boolean">true</time-tracking>
 23 |   </subscription>
 24 |   <default-attachment-categories>
 25 |     <category>Documents</category>
 26 |     <category>Pictures</category>
 27 |     <category>Sounds</category>
 28 |   </default-attachment-categories>
 29 |   <default-post-categories>
 30 |     <category>Design</category>
 31 |     <category>Code</category>
 32 |     <category>Copywriting</category>
 33 |     <category>Transcripts</category>
 34 |     <category>Assets</category>
 35 |     <category>Miscellaneous</category>
 36 |   </default-post-categories>
 37 | </account>
 38 | ```
 39 | 
 40 | Attachment
 41 | ----------
 42 | 
 43 | ``` xml
 44 | <attachment>
 45 |   <id type="integer">#{id}</id>
 46 |   <name>#{name}</name>
 47 |   <description>#{description}</description>
 48 |   <byte-size type="integer">#{byte_size}</byte-size>
 49 |   <download-url>#{download_url}</download-url>
 50 | 
 51 |   <project-id type="integer">#{project_id}</project-id>
 52 |   <category-id type="integer">#{category_id}</category-id>
 53 |   <person-id type="integer">#{person_id}</person-id>
 54 |   <private type="boolean">#{private}</private>
 55 |   <created-on type="datetime">#{created_on}</created-on>
 56 | 
 57 |   <!-- if the attachment belongs to a message or comment -->
 58 |   <owner-id type="integer">#{owner_id}</owner-id>
 59 |   <owner-type>#{owner_type}</owner-type>
 60 | 
 61 |   <!-- for attachments with multiple versions, collection specifies
 62 |     the id of the "parent" attachment (version 1), and current will
 63 |     be true for the most recent version -->
 64 |   <collection type="integer">#{collection}</collection>
 65 |   <version type="integer">#{version}</version>
 66 |   <current type="boolean">#{current}</current>
 67 | </attachment>
 68 | ```
 69 | 
 70 | Calendar entry
 71 | --------------
 72 | 
 73 | ``` xml
 74 | <calendar-entry>
 75 |   <id type="integer">#{id}</id>
 76 |   <title>#{title}</title>
 77 |   <type>#{Milestone|CalendarEvent}</type>
 78 |   <start-at type="date">#{start_at}</start-at>
 79 |   <deadline type="{date|datetime}">#{deadline}</deadline>
 80 |   <project-id type="integer">#{project_id}</project-id>
 81 |   <created-on type="datetime">#{created_on}</created-on>
 82 |   <creator-id type="integer">#{creator_id}</creator-id>
 83 |   <creator-name>#{creator_name}</creator-name>
 84 |   <commented-at type="datetime">#{commented_at}</commented-at>
 85 |   <comments-count type="integer">#{comments_count}</comments-count>
 86 | 
 87 |   <!-- if the entry is a milestone -->
 88 |   <completed type="boolean">#{true|false}</completed>
 89 |   <responsible-party-id type="integer">#{responsible_party_id}</responsible-party-id>
 90 |   <responsible-party-type>#{responsible_party_type}</responsible-party-type>
 91 |   <responsible-party-name>#{responsible_party_name}</responsible-party-name>
 92 | 
 93 |   <!-- if the milestone has been completed -->
 94 |   <completed-on type="datetime">#{completed_on}</completed-on>
 95 |   <completer-id type="integer">#{completer_id}</completer-id>
 96 |   <completer-name>#{completer_name}</completer-name>
 97 | </calendar-entry>
 98 | ```
 99 | 
100 | Category
101 | --------
102 | 
103 | ``` xml
104 | <category>
105 |   <id type="integer">#{id}</id>
106 |   <name>#{name}</name>
107 |   <project-id type="integer">#{project_id}</project-id>
108 |   <elements-count type="integer">#{elements_count}</elements-count>
109 |   <type>#{type}</type>
110 | </category>
111 | ```
112 | 
113 | Comment
114 | -------
115 | 
116 | ``` xml
117 | <comment>
118 |   <id type="integer">#{id}</id>
119 |   <author-id type="integer">#{author_id}</author-id>
120 |   <author-name>#{author_name}</author-name>
121 |   <commentable-id type="integer">#{commentable_id}</commentable-id>
122 |   <commentable-type>#{commentable_type}</commentable-type>
123 |   <body>#{body}</body>
124 |   <emailed-from nil="true">#{emailed_from}</emailed-from>
125 |   <created-at type="datetime">#{created_at}</created-at>
126 | 
127 |   <attachments-count type="integer">#{attachments_count}</attachments-count>
128 |   <attachments type="array">
129 |     <attachment>
130 |       ...
131 |     </attachment>
132 |     ...
133 |   </attachments>
134 | </comment>
135 | ```
136 | 
137 | Company
138 | -------
139 | 
140 | ``` xml
141 | <company>
142 |   <id type="integer">#{id}</id>
143 |   <name>#{name}</name>
144 |   <address-one>#{address_one}</address-one>
145 |   <address-two>#{address_two}</address-two>
146 |   <city>#{city}</city>
147 |   <state>#{state}</state>
148 |   <zip>#{zip}</zip>
149 |   <country>#{country}</country>
150 |   <web-address>#{web_address}</web-address>
151 |   <phone-number-office>#{phone_number_office></phone-number-office>
152 |   <phone-number-fax>#{phone_number_fax}</phone-number-fax>
153 |   <time-zone-id>#{time_zone_id}</time-zone-id>
154 |   <can-see-private type="boolean">#{can_see_private}</can-see-private>
155 | 
156 |   <!-- for non-client companies -->
157 |   <url-name>#{url_name}</url-name>
158 | </company>
159 | ```
160 | 
161 | Milestone
162 | ---------
163 | 
164 | ``` xml
165 | <milestone>
166 |   <id type="integer">#{id}</id>
167 |   <title>#{title}</title>
168 |   <deadline type="date">#{deadline}</deadline>
169 |   <completed type="boolean">#{true|false}</completed>
170 |   <project-id type="integer">#{project_id}</project-id>
171 |   <created-on type="datetime">#{created_on}</created-on>
172 |   <creator-id type="integer">#{creator_id}</creator-id>
173 |   <creator-name>#{creator_name}</creator-name>
174 |   <responsible-party-id type="integer">#{responsible_party_id}</responsible-party-id>
175 |   <responsible-party-type>#{responsible_party_type}</responsible-party-type>
176 |   <responsible-party-name>#{responsible_party_name}</responsible-party-name>
177 |   <commented-at type="datetime">#{commented_at}</commented-at>
178 |   <comments-count type="integer">#{comments_count}</comments-count>
179 | 
180 |   <!-- if the milestone has been completed -->
181 |   <completed-at type="datetime">#{completed_at}</completed-at>
182 |   <completer-id type="integer">#{completer_id}</completer-id>
183 |   <completer-name>#{completer_name}</completer-name>
184 | </milestone>
185 | ```
186 | 
187 | Person
188 | ------
189 | 
190 | ``` xml
191 | <person>
192 |   <id type="integer">#{id}</id>
193 |   <first-name>#{first_name}</first-name>
194 |   <last-name>#{last_name}</last-name>
195 |   <title>#{title}</title>
196 |   <email-address>#{email_address}</email-address>
197 |   <im-handle>#{im_handle}</im-handle>
198 |   <im-service>#{im_service}</im-service>
199 |   <phone-number-office>#{phone_number_office}</phone-number-office>
200 |   <phone-number-office-ext>#{phone_number_office_ext}</phone-number-office-ext>
201 |   <phone-number-mobile>#{phone_number_mobile}</phone-number-mobile>
202 |   <phone-number-home>#{phone_number_home}</phone-number-home>
203 |   <phone-number-fax>#{phone_number_fax}</phone-number-fax>
204 |   <company-id type="integer">#{company_id}</company-id>
205 |   <client-id type="integer">#{client_id}</client-id>
206 |   <time-zone-name>#{time_zone_name}</time-zone-name>
207 | 
208 |   <avatar-url>#{avatar_url}</avatar-url>
209 | 
210 |   <!-- if user is an administrator, or is self -->
211 |   <user-name>#{user_name}</user-name>
212 | 
213 |   <!-- if user is an administrator -->
214 |   <administrator type="boolean">#{administrator}</administrator>
215 |   <deleted type="boolean">#{deleted}</deleted>
216 |   <has-access-to-new-projects type="boolean">#{has_access_to_new_projects}</has-access-to-new-projects>
217 | </person>
218 | ```
219 | 
220 | Post
221 | ----
222 | 
223 | ``` xml
224 | <post>
225 |   <id type="integer">#{id}</id>
226 |   <title>#{title}</title>
227 |   <body>#{body}</body>
228 |   <display-body>#{display_body}</display-body>
229 |   <posted-on type="datetime">#{posted_on}</posted-on>
230 |   <commented-at type="datetime">#{commented_at}</commented-at>
231 |   <project-id type="integer">#{project_id}</project-id>
232 |   <category-id type="integer">#{category_id}</category-id>
233 |   <author-id type="integer">#{author_id}</author-id>
234 |   <author-name>#{author_name}</author-name>
235 |   <milestone-id type="integer">#{milestone_id}</milestone-id>
236 |   <comments-count type="integer">#{comments_count}</comments-count>
237 |   <use-textile type="boolean">#{use_textile}</use-textile>
238 |   <extended-body deprecated="true">#{extended_body}</extended-body>
239 |   <display-extended-body deprecated="true">#{display_extended_body}</display-extended-body>
240 | 
241 |   <attachments-count type="integer">#{attachments_count}</attachments-count>
242 |   <attachments type="array">
243 |     <attachment>
244 |       ...
245 |     </attachment>
246 |     ...
247 |   </attachments>
248 | 
249 |   <!-- if user can see private posts -->
250 |   <private type="boolean">#{private}</private>
251 | </post>
252 | ```
253 | 
254 | Post (Abbreviated)
255 | ------------------
256 | 
257 | ``` xml
258 | <post>
259 |   <id type="integer">#{id}</id>
260 |   <title>#{title}</title>
261 |   <author-name>#{author_name}</author-name>
262 |   <posted-on type="datetime">#{posted_on}</posted-on>
263 |   <commented-at type="datetime">#{commented_at}</commented-at>
264 |   <attachments-count type="integer">#{attachments_count}</attachments-count>
265 |   <category>
266 |     <id type="integer">#{id}</id>
267 |     <name>#{name}</name>
268 |   </category>
269 | </post>
270 | ```
271 | 
272 | Project
273 | -------
274 | 
275 | ``` xml
276 | <project>
277 |   <id type="integer">#{id}</id>
278 |   <name>#{name}</name>
279 |   <created-on type="datetime">#{created_on}</created-on>
280 |   <status>#{status}</status>
281 |   <last-changed-on type="datetime">#{last_changed_on}</last-changed-on>
282 |   <company>
283 |     <id type="integer">#{id}</id>
284 |     <name>#{name}</name>
285 |   </company>
286 | 
287 |   <!-- if user is administrator, or show_announcement is true -->
288 |   <announcement>#{announcement}</announcement>
289 | 
290 |   <!-- if user is administrator -->
291 |   <start-page>#{start_page}</start-page>
292 |   <show-writeboards type="boolean">#{show_writeboards}</show-writeboards>
293 |   <show-announcement type="boolean">#{show_announcement}</show-announcement>
294 | </project>
295 | ```
296 | 
297 | Subscription
298 | ------------
299 | 
300 | ``` xml
301 | <subscription>
302 |   <name>Premium</name>
303 |   <writeboards type="float">Infinity</writeboards>
304 |   <projects type="integer">100</projects>
305 |   <storage type="integer">32212254720</storage>
306 |   <ssl type="boolean">true</ssl>
307 |   <time-tracking type="boolean">true</time-tracking>
308 | </subscription>
309 | ```
310 | 
311 | Time entry
312 | ----------
313 | 
314 | ``` xml
315 | <time-entry>
316 |   <id type="integer">#{id}</id>
317 |   <project-id type="integer">#{project_id}</project-id>
318 |   <person-id type="integer">#{person_id}</person-id>
319 |   <person-name>#{person_name}</person-name>
320 |   <date type="date">#{date}</date>
321 |   <hours>#{hours}</hours>
322 |   <description>#{description}</description>
323 |   <todo-item-id type="integer">#{todo_item_id}</todo-item-id>
324 | </time-entry>
325 | ```
326 | 
327 | Todo item
328 | ---------
329 | 
330 | ``` xml
331 | <todo-item>
332 |   <id type="integer">#{id}</id>
333 |   <todo-list-id type="integer">#{todo_list_id}</todo-list-id>
334 |   <content>#{content}</content>
335 |   <position type="integer">#{position}</position>
336 |   <created-on type="datetime">#{created_on}</created-on>
337 |   <creator-id type="integer">#{creator_id}</creator-id>
338 |   <creator-name>#{creator_name}</creator-name>
339 |   <completed type="boolean">#{completed}</completed>
340 |   <updated-at type="datetime">#{updated_at}</updated-at>
341 |   <commented-at type="datetime">#{commented_at}</commented-at>
342 |   <comments-count type="integer">#{comments_count}</comments-count>
343 | 
344 |   <!-- if the item has a due date (in the company time zone) -->
345 |   <due-at type="datetime">#{due_at}</due-at>
346 | 
347 |   <!-- if the item has a responsible party -->
348 |   <responsible-party-type>#{responsible_party_type}</responsible-party-type>
349 |   <responsible-party-id type="integer">#{responsible_party_id}</responsible-party-id>
350 |   <responsible-party-name>#{responsible_party_name}</responsible-party-name>
351 | 
352 |   <!-- if the item has been completed -->
353 |   <completed-at type="datetime">#{completed_at}</completed-at>
354 |   <completer-id type="integer">#{completer_id}</completer-id>
355 |   <completer-name>#{completer_name}</completer-name>
356 | </todo-item>
357 | ```
358 | 
359 | Todo list
360 | ---------
361 | 
362 | ``` xml
363 | <todo-list>
364 |   <id type="integer">#{id}</id>
365 |   <name>#{name}</name>
366 |   <description>#{description}</description>
367 |   <project-id type="integer">#{project_id}</project-id>
368 |   <milestone-id type="integer">#{milestone_id}</milestone-id>
369 |   <position type="integer">#{position}</position>
370 |   <completed type="boolean">#{completed}</completed>
371 | 
372 |   <!-- if user can see private lists -->
373 |   <private type="boolean">#{private}</private>
374 | 
375 |   <!-- if the account supports time tracking -->
376 |   <tracked type="boolean">#{tracked}</tracked>
377 | 
378 |   <!-- if todo-items are included in the response -->
379 |   <todo-items type="array">
380 |     <todo-item>
381 |       ...
382 |     </todo-item>
383 |     <todo-item>
384 |       ...
385 |     </todo-item>
386 |     ...
387 |   </todo-items>
388 | </todo-list>
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 | <attachments>
17 |   <attachment>
18 |     ...
19 |   </attachment>
20 |   <attachment>
21 |     ...
22 |   </attachment>
23 |   ...
24 | </attachments>
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 | <posts>
 20 |   <post>
 21 |     ...
 22 |   </post>
 23 |   ...
 24 | </posts>
 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 | <post>
 38 |   ...
 39 | </post>
 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 | <posts>
 56 |   <post>
 57 |     ... <!-- abbreviated post -->
 58 |   </post>
 59 |   <post>
 60 |     ... <!-- abbreviated post -->
 61 |   </post>
 62 |   ...
 63 | </posts>
 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 | <post>
 78 |   ...
 79 | </post>
 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 | <request>
 95 |   <post>
 96 |     <category-id>#{category_id}</category-id>
 97 |     <title>#{title}</title>
 98 |     <body>#{body}</body>
 99 |     <private>1</private> <!-- only for firm employees -->
100 |   </post>
101 |   <notify>#{person_id}</notify>
102 |   <notify>#{person_id}</notify>
103 |   ...
104 |   <attachments>
105 |     <name>#{name}</name> <!-- optional -->
106 |     <file>
107 |       <file>#{temp_id}</file> <!-- the id of the previously uploaded file -->
108 |       <content-type>#{content_type}</content-type>
109 |       <original-filename>#{original_filename}</original-filename>
110 |     </file>
111 |   </attachments>
112 |   <attachments>...</attachments>
113 |   ...
114 | </request>
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 | <post>
133 |   ...
134 | </post>
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 | <request>
150 |   <post>
151 |     <category-id>#{category_id}</category-id>
152 |     <title>#{title}</title>
153 |     <body>#{body}</body>
154 |     <private>1</private> <!-- only for firm employees -->
155 |     <notify-about-changes>1</notify-about-changes>
156 |   </post>
157 |   <notify>#{person_id}</notify>
158 |   <notify>#{person_id}</notify>
159 |   ...
160 | </request>
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 | <person>
15 |   <id type="integer">#{id}</id>
16 |   <user-name>#{user_name}</user-name>
17 |   ...
18 | </person>
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 | <people>
35 |   <person>
36 |     ...
37 |   </person>
38 |   ...
39 | </people>
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 | <person>
52 |   ...
53 | </person>
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 | <projects>
 15 |   <project>
 16 |     ...
 17 |   </project>
 18 |   <project>
 19 |     ...
 20 |   </project>
 21 |   ...
 22 | </projects>
 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 | <project>
 36 |   <name>Design Review</name>
 37 |   ...
 38 |   <company>
 39 |     <name>Globex Corporation</name>
 40 |     ...
 41 |   </company>
 42 | </project>
 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 | <request>
 56 |   <project>
 57 |     <name>Shopping Cart Redesign</name>
 58 |   </project>
 59 | </request>
 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 | <project>
 79 |   <name type="string">Shopping Cart Redesign</name>
 80 |   <start-page type="string">log|all|todos|milestones|files</start-page>
 81 |   <status>active|on_hold|archived</status>
 82 |   <company-id>#{client-id}</company-id>
 83 |   <show-writeboards>true|false</show-writeboards>
 84 |   <announcement>...</announcement>
 85 |   <show-announcement>true|false</show-announcement>
 86 | </project>
 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 | <count>
106 |   <active type="integer">5</active>
107 |   <on-hold type="integer">2</active>
108 |   <archived type="integer">11</active>
109 | </count>
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 | <time-entries type="array">
 18 |   <time-entry>
 19 |     ...
 20 |   </time-entry>
 21 |   ...
 22 | </time-entries>
 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 | <time-entry>
 36 |   <person-id>#{person-id}</person-id>
 37 |   <date>#{date}</date>
 38 |   <hours>#{hours}</hours>
 39 |   <description>#{description}</description>
 40 | </time-entry>
 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 | <time-entry>
 59 |   ...
 60 | </time-entry>
 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 | <time-entry>
 73 |   ...
 74 | </time-entry>
 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 | <time-entry>
 89 |   ...
 90 | </time-entry>
 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 | <time-entry>
103 |   <person-id>#{person-id}</person-id>
104 |   <date>#{date}</date>
105 |   <hours>#{hours}</hours>
106 |   <description>#{description}</description>
107 | 
108 |   <!-- if associated with a todo-item -->
109 |   <todo-item-id>#{todo-item-id}</todo-item-id>
110 | </timeentry>
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 | <time-entries type="array">
139 |   <time-entry>
140 |     ...
141 |   </time-entry>
142 |   ...
143 | </time-entries>
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 | <todo-items type="array">
 17 |   <todo-item>
 18 |     ...
 19 |   </todo-item>
 20 |   ...
 21 | </todo-items>
 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 | <todo-item>
 34 |   ...
 35 | </todo-item>
 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 | <todo-item>
 72 |   ...
 73 | </todo-item>
 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 | <todo-item>
 88 |   <content>#{content}</content>
 89 | 
 90 |   <!-- if the item has a due date (in the company time zone) -->
 91 |   <due-at>#{due_at}</due-at>
 92 | 
 93 |   <!-- if the item has a responsible party -->
 94 |   <responsible-party>#{party_id}</responsible-party>
 95 |   <notify type="boolean">#{true|false}</notify>
 96 | </todo-item>
 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 | <todo-item>
115 |   <content>#{content}</content>
116 | 
117 |   <!-- if the item has a responsible party -->
118 |   <responsible-party>#{party_id}</responsible-party>
119 |   <notify type="boolean">#{true|false}</notify>
120 | </todo-item>
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 | <todo-item>
139 |   ...
140 | </todo-item>
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 | <todo-items type="array">
165 |   <todo-item><id>#{id}</id></todo-item>
166 |   ...
167 | </todo-items>
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 | <todo-lists array="true">
 18 |   <todo-list>
 19 |     ...
 20 |     <todo-items array="true">
 21 |       <todo-item>
 22 |         ...
 23 |       </todo-item>
 24 |     </todo-items>
 25 |   </todo-list>
 26 |   ...
 27 | </todo-lists>
 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 | <todo-lists array="true">
 43 |   <todo-list>
 44 |     ...
 45 |   </todo-list>
 46 |   ...
 47 | </todo-lists>
 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 | <todo-list>
 60 |   ...
 61 | </todo-list>
 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 | <todo-list>
 77 |   ...
 78 | </todo-list>
 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 | <todo-list>
 92 |   <name>#{name}</name>
 93 |   <description>#{description}</description>
 94 |   <milestone-id>#{milestone_id}</milestone-id>
 95 |   <private type="boolean">#{true|false}</private>
 96 |   <tracked type="boolean">#{true|false}</tracked> <!-- enable/disable time tracking -->
 97 | </todo-list>
 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 | <todo-list>
116 |   ...
117 | </todo-list>
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 | <todo-list>
132 |   <name>#{name}</name>
133 |   <description>#{description}</description>
134 |   <milestone-id>#{milestone_id}</milestone-id> <!-- optional -->
135 |   <private type="boolean">#{true|false}</private> <!-- optional -->
136 |   <tracked type="boolean">#{true|false}</tracked> <!-- enable/disable time tracking -->
137 | 
138 |   <!-- if based on an existing todo-list template -->
139 |   <todo-list-template-id>#{template_id}</todo-list-template-id>
140 | </todo-list>
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 | <todo-lists type="array">
169 |   <todo-list><id>...</id></todo-list>
170 |   <todo-list><id>...</id></todo-list>
171 |   ...
172 | </todo-lists>
173 | ```
174 | 
175 | **Response:**
176 | 
177 | Returns HTTP status code 200 on success.
178 | 


--------------------------------------------------------------------------------