API Introduction
The Trello API is extremely powerful and fun to use. Building a full application with Trello for web or mobile means getting to know the various concepts and models making up Trello.
We're going to walk you through getting your API key and token, making a few requests, and then give a high-level look at some of the most popular API resources.
Managing your API Key
Trello uses a delegated authentication and authorization flow so that your application never has to deal with storing or handling usernames or passwords. Instead, your application passes control to Trello (identifying itself via the API key) and once Trello has allowed the user to choose an account and sign in, Trello will hand the user and control back to your application, along with an API Token.
To get started, you’ll need an API key. For generating an API key, you first need to have created a Trello Power-Up. You can check our Managing Power-Ups documentation to get information on how to create your first Power-Up. Once you already have created a Power-Up, you can visit the https://trello.com/power-ups/admin page, access your Power-Up, navigate to the API Key tab and select the option Generate a new API Key.
Because of the way the authorization flow works, the API key is intended to be publicly accessible. An API key by itself doesn't grant access to a user's Trello data. However, because API tokens grant access to the user's data, they should be kept secret.
Authentication and Authorization
For the purposes of this walkthrough, we'll have you generate a token for yourself. On the same page where you found your API key, click the hyperlinked "Token" at the right of the API key. You should be prompted with the following screen:
Your users will always see this screen when granting your application access. The permissions, duration of access, and application name displayed are all configured via the URL parameters. More on that at Authorization. But we'll leave everything as is, and click "Allow".
Once you click Allow you'll grant your own app (identified via your API key) access to your account and be redirected to a page that contains the API token.
This token, along with your API key, can be used to read and write for your entire Trello account. Tokens should be kept secret!
Your First API Call
Now that you have the API key and token for your account, you can use them to start making requests. One of the most popular resources in Trello is the boards object. So we will start by getting all of the boards that belong to your user.
You can make a GET request to the 1/members/{memberId}/boards resource and list all of the boards associated with a member, in this case, you.
1 2curl 'https://api.trello.com/1/members/me/boards?key={yourKey}&token={yourToken}'
Be sure to replace the {yourKey} and {yourToken} parameters with the key and token values from above.
You may be wondering how Trello knows to associate the request with your account. Although the documented route specifies that a memberId needs to be passed in as a URL parameter, we're passing in the me shortcut. Trello interprets the me in the place of a memberID as a reference to the user who is making the request based on the API token (remember, the API token belongs to a specific user). In this case, me is referring to you because the token was generated on behalf of your Trello account.
Once you've made the request above, you'll receive a response that contains a JSON object with information about all of the boards you belong to. Want to get more information on a particular board? Let’s grab one of the board IDs from the JSON response you just received and plug it into the following request:
1 2curl 'https://api.trello.com/1/boards/{idBoard}?key={yourKey}&token={yourToken}'
From here there are a lot of directions you can go. So now we'll tell you a little bit about the most popular resources and the ones that are core to working with Trello. Of course, you can also head over to the full REST API Docs to see everything that is available!
Where to start?!
A lot of folks getting started ask, How do I just get cards? Which makes sense because cards are the fundamental unit in Trello! But cards only exist within the context of boards. And all boards belong to a member or Workspace. So to get started getting cards, you'll first have to make a few requests to board–don't worry, it's easy; just follow along below!
Boards
Boards are where the majority of work happens. Trello boards can have multiple members that can create and edit cards, they can belong to a user (private boards) or belong to a Workspace (organization boards), and boards may have any number of lists on them. The Boards API allows you to list, view, create, and edit Boards. Each Board has a set of fields that you can update (like name and description), as well as sets of sub resources that can be updated (like members and lists).
The full Boards API reference is loaded with all of the possible requests you could make and there sure are A LOT! But, to get started, let's get the name of a board that our member belongs to and then update the board's name.
GETting Our Member's Boards
First, we'll make a GET request and ask Trello to only return the names and URLs of the boards that belong to our member.
Plural or Singular Routes
Trello's API supports both singular and plural nouns in the route. For instance /1/members/me and /1/member/me will both return the same thing.
Here is the request we'll make via curl in a terminal:
1 2curl https://api.trello.com/1/members/me/boards?fields=name,url&key={apiKey}&token={apiToken}
This will return a JSON array of all of the boards that our member can see:
1 2[ { "name": "Greatest Product Roadmap", "id": "5b6893f01cb3228998cf629e", "url": "https://trello.com/b/Fqd6NosI/greatest-product-roadmap" }, // ... There may be a lot of boards here if you've been using // Trello a lot! { "name": "Never ending Backlog", "id": "5b689b3228998cf3f01c629e", "url": "https://trello.com/b/pLu77kV7/neverending-backlog" }, { "name": "3T Board 5/21/2018", "id": "5b6893f998cf62901cb3228e", "url": "https://trello.com/b/b3wi9yUu/3t-board-5-21-2018" }, {
In our request, we included the fields query parameter and asked for only the url and name to be returned. But we can see in our response, we also received the ID. This is because the ID is always implicitly returned.
Now, if we wanted to get more information about a specific board, for instance, the "Greatest Product Roadmap" board, we could make a GET request with its ID. This time, we'll make a request for all of the fields:
1 2curl https://api.trello.com/1/members/me/boards?fields=name,url&key={apiKey}&token={apiToken}
And the response will be a JSON object that includes all of the fields on a board.
Similarly, if we want to update a field on the board we can make a PUT request to the /1/boards route with the ID of the board we want to update. To update our Great Product Roadmap board's name, we would make a request like the following:
1 2curl -X PUT https://api.trello.com/1/boards/5b6893f01cb3228998cf629e?key={apiKey}&token={apiToken} -d '{ "name": "This Is Just A Tribute" }' --header "Content-Type: application/json"
This time, our response will be a JSON version of the board with an updated name!
Lists
A List is a collection of Cards. In the standard Trello interface, Lists are stacked horizontally and are ordered on a board.
Important Methods
GET /1/lists/[idList]/cards - Get an array of Cards on a List
POST /1/cards - Create a new Card on a List
Cards
A Card is the most basic unit of information in Trello. Cards have a name, description, labels, members, and a set of historical actions that have been taken on the card, including any comments.
Important Methods
POST /1/cards - Create a new card on a List
PUT /1/cards/[card id or shortlink] - Update the contents of a Card
POST /1/cards/[card id or shortlink]/actions/comments - Add a comment to a Card
POST /1/cards/[card id or shortlink]/idMembers - Add a member to a Card
Child Methods
Actions - Actions are the audit log / record of everything that has been done to a card throughout its history, including any comments that have been made.
Labels - Labels can be as simple as colors attached to a Card, or Labels can have names.
Actions
Actions contain each of the actions that have been taken on a Card or Board or members of a Card. Comments are also stored as a special type of Action on a card.
The API limits Action queries to 1000 at a time. Actions can be queried at the Board or at the Card level. To retrieve the full list of actions when there are more then 1000, multiple requests must be made using the since and before parameters.
Webhooks
A developer could theoretically parse a user's Boards, Lists, and Cards in order to get all of the information, but this would mean loading a lot of data that doesn't change very often, using more bandwidth, CPU, and RAM for both you and for our servers. To mitigate this we have built a system that allows your application to hook into updates on various members such as Boards, Lists, and Cards. Whenever a member with a Webhook is changed, we make an HTTP request to the endpoint of your choosing.
Important Methods
POST /1/webhooks - Create a Webhook
GET /1/tokens/{token}/webhooks - Get an array of the Webhooks associated with your token
DELETE /1/webhooks/{idWebhook} - Delete a Webhook
Paging
When querying for long lists, such as a list of Cards, or a list of Actions, the Trello API limits you to at most 1000 results. Because these lists can have members added or removed at any time, the right way to iterate through more than 1000 results is to use the before and since parameters.
These parameters operate on the creation date of the Card or Action. The API expects a ISO 8601 date format. Because we use standard Mongo IDs, you can actually derive the Card creation date from the Card ID. (Here is one such tool: https://steveridout.github.io/mongo-object-time/). As a convenience, you can also pass in the ID of a Card or Action and we will derive the date for you.
This means to page through the Actions on a large Board, you should request the Actions and then pass the ID of the last Action as the before parameter.
Recursion Helpers
Several of the core methods allow you to directly access member content. For example, instead of retrieving a list and then recursively requesting each of the cards on the list, you can retrieve this information directly, and optionally supply a filter for the child cards.
Example Recursions
GET /1/member/me/boards/?actions=all
GET /1/lists/[idList]/cards/[filter]
Search
The Trello API offers the ability to search all the actions, boards, cards, members, and organizations. While you can't control which fields you want to search, you can specify which fields you want your search to return. By passing in a single string, we will look at all of the relevant fields and return a list of all those matching models.
Example Search Request
GET /1/search?query=Wedding
This search will return a list of actions, boards, cards, members, and organizations that match "Wedding".
API Rate Limits
To help prevent strain on Trello’s servers, our API imposes rate limits per API key for all issued tokens. If a request exceeds the limit, Trello will return a 429 error along with a message corresponding to which limit was exceeded.
For more on rate limits, read the full documentation here.
The best option is often to use our webhooks infrastructure instead of polling Trello’s API. There is no limit to the number of webhooks you can set up in Trello. Our webhook documentation is located here.
client.js
If you're looking for info on getting started with client.js, head on over to Getting Started with client.js.
Not sure what client.js is? It is a javascript library that wraps Trello's REST API and provides a few helper functions to make it easier to make requests!
Rate this page: