The Basecamp 3 API
Welcome to the Basecamp 3 API! If you're looking to integrate your application with Basecamp 3 or create your own application in concert with data inside of Basecamp 3, you're in the right place. We're happy to have you!
Compatibility with previous Basecamp APIs
The Basecamp 3 API is not compatible with the Basecamp Classic API or the Basecamp 2 API. All integrations will start fresh with the new API. The core ingredients are the same, though: Basecamp 3 is a REST-style API that uses JSON for serialization and OAuth 2.0 for authentication.
What's different?
If you've used a previous version of the Basecamp API, you need to adapt your integration code. Here are some notable changes for the Basecamp 3 API:
- We require OAuth 2.0 for authentication—no more Basic authentication
- All requests must end in
.json
- Pagination is performed via the
Link
andX-Total-Count
headers - Projects are called Basecamps
Making a request
All URLs start with https://3.basecampapi.com/999999999/
. URLs are HTTPS only. The path is prefixed with the account ID, but no /api/v1
API prefix. Also, note the different domain!
To make a request for all the projects on your account, append the projects
index path to the base URL to form something like https://3.basecampapi.com/999999999/projects.json
. In cURL, it looks like this:
curl -H "Authorization: Bearer $ACCESS_TOKEN" -H 'User-Agent: MyApp (yourname@example.com)' https://3.basecampapi.com/999999999/projects.json
To create something, it's the same idea, but you also have to include the Content-Type
header and the JSON data:
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (yourname@example.com)' \
-d '{ "name": "My new project!" }' \
https://3.basecampapi.com/999999999/projects.json
Throughout the Basecamp 3 API docs, we include "Copy as cURL" examples. To try the examples in your shell, copy your OAuth 2.0 access token into your clipboard and run:
export ACCESS_TOKEN=PASTE_ACCESS_TOKEN_HERE
export ACCOUNT_ID=999999999
Then you should be able to copy/paste any example from the docs. After pasting a cURL example, you can pipe it to a JSON pretty printer to make it more readable. Try jsonpp or json_pp
on OSX:
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/999999999/projects.json | json_pp
Authentication
If you're making a public integration with Basecamp for others to enjoy, you must use OAuth 2.0. OAuth 2.0 allows users to authorize your application to use Basecamp on their behalf without having to copy/paste API tokens or touch sensitive login information.
Read the authentication guide to get started.
Identifying your application
You must include a User-Agent
header with both:
- The name of your application
- A link to your application or your email address
We use this information to get in touch if you're doing something wrong (so we can warn you before you're blacklisted) or something awesome (so we can congratulate you). Here are examples of acceptable User-Agent
headers:
User-Agent: Freshbooks (http://freshbooks.com/contact.php)
User-Agent: Fabian's Ingenious Integration (fabian@example.com)
If you don't include a User-Agent
header, you'll get a 400 Bad Request
response.
JSON only
We use JSON for all API data. The style is no root element and snake_case for object keys. This means that you have to send the Content-Type
header Content-Type: application/json; charset=utf-8
when you're POSTing or PUTing data into Basecamp. All API URLs end in .json
to indicate that they return JSON.
You'll receive a 415 Unsupported Media Type
response code if you don't include the Content-Type
header or you try to use a different URL suffix than .json
.
Pagination
Most collection APIs paginate their results. The first request returns up to 50 records. The Basecamp 3 API follows the RFC5988 convention of using the Link
header to provide URLs for the next
page. Follow this convention to retrieve the next page of data—please don't build the pagination URLs yourself!
Here's an example response header from requesting the third page of messages:
Link: <https://3.basecampapi.com/999999999/buckets/2085958496/messages.json?page=4>; rel="next"
If the Link
header is blank, that's the last page. The Basecamp 3 API also provides the X-Total-Count
header, which displays the total number of resources in the collection you are fetching.
Using HTTP caching
You must use HTTP freshness headers to speed up your application and lighten the load on our servers. Most API responses will include an ETag
or Last-Modified
header. When you first request a resource, store these values. On subsequent requests, submit them back to us as If-None-Match
and If-Modified-Since
, respectively. If the resource hasn't changed since your last request, you'll get a 304 Not Modified
response with no body, saving you the time and bandwidth of sending something you already have.
Handling errors
If Basecamp is having trouble, you might get a 5xx error. 500
means that the application is entirely down, but 502 Bad Gateway
, 503 Service Unavailable
, or 504 Gateway Timeout
errors are also possible. In all of these cases, it's your responsibility to retry your request later.
Rate limiting
You can perform up to 50 requests per 10-second period from the same IP address for the same account. If you exceed this limit, you'll get a 429 Too Many Requests response for subsequent requests. Check the Retry-After
header to learn how many seconds to wait before retrying the request.
We recommend baking 429 response-handling in to your HTTP handling at a low level so your integration handles retries gracefully and automatically.
Rich text content
Many resources, including messages, documents, and comments, represent their content as rich text in HTML. Rich text content may contain lists, block quotes, simple formatting, and inline attachments such as mentions, images, and files.
See the Rich text section for more information about working with HTML and attachments in rich text content.
API endpoints
- Attachments
- Basecamps
- Campfires
- Chatbots
- Client approvals
- Client correspondences
- Client replies
- Comments
- Documents
- Events
- Forwards
- Inboxes
- Message Boards
- Messages
- People
- Question answers
- Questionnaires
- Questions
- Recordings
- Schedule entries
- Schedules
- Templates
- To-do lists
- To-dos
- To-do sets
- Uploads
- Vaults
- Webhooks
Listing your application
To add your application to our public list of Basecamp 3 integrations, go to https://github.com/basecamp/bc3-integrations and open a pull request.
Conduct
Please note that this project is released with a Contributor Code of Conduct. By participating in discussions about the Basecamp 3 API, you agree to abide by these terms.
License
These API docs are licensed under Creative Commons (CC BY-SA 4.0). Please share, remix, and distribute as you see fit.
If you have a specific feature request or find a bug, please open a GitHub issue. We encourage you to fork these docs for local reference and happily accept pull requests with improvements.
To talk with us and other developers about the API, post a question on StackOverflow tagged basecamp
. If you need help from us directly, please open a support ticket.