Trello Developers

API Introduction

A walkthrough of getting started with Trello's RESTful API, making your first request, and an overview of the most important Trello resources!

The Trello API is extremely powerful. We use the same API in the Trello web and mobile clients! Building a full application with Trello means getting to know the various concepts and models in Trello.

We're going to walk you through getting your API key and token, making a few requests, and then give you a high-level look at some of the most popular API resources.

Authentication and Authorization

If you already have your API key and token, feel free to head down to Your First API Call below.

You'll need two things before you and your application can make a call on behalf of a user to the Trello API. The first thing you'll need is your API key. Every Trello user gets a single API key; it is used to identify you and your applications to Trello.

You can get your API key by logging into Trello and visiting https://trello.com/app-key. Your API key should be 32 character string comprised of random alphanumeric characters.

The second thing you need to make a request is an API token. 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.

Because of this authorization flow, 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.

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 (https://trello.com/app-key), you should see a section below the key that reads:

Most developers will need to ask each user to __authorize__ your application. If you are looking to build an application for yourself, or are doing local testing, you can manually generate a __Token__.

Click on the hyperlinked "Token" and 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.

Once you click Allow you'll grant your own app access to your account and be redirected to a page that contains the API token. Remember, this token can be used to access all of your Trello account so keep it safe!

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 to list all of the board.

curl 'https://api.trello.com/1/members/me/boards?key={yourKey}&token={yourToken}'

You can make the request above in a web browser or with bash using curl. Be sure to replace the {yourKey} and {yourToken} parameters with the key and token values from above.

Although the documented route specifies that a memberId be passed in as a URL parameter, we're passing in the me shortcut. Trello interprets me in the place of a memberID as a reference to the user who is making the request based on the API token. 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 board? Grab one of the board IDs from the JSON response you just received and plug it into the following GET request:

curl 'https://api.trello.com/1/boards/{idBoard}?key={yourKey}&token={yourToken}'

That will give you all of the default fields for the Boards resource.

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!

Boards

Full Boards API Reference

Boards are the highest level concept within the Trello workflow. The Boards API allows you to list, view, create, and edit Boards. Each Board has a name, description, a set of members attached, and an ordered array of Lists.

Boards can be open or closed, starred, and/or subscribed. Each Board belongs to an organization. Each board also has a set of preferences that affect its visual display, and additional features that may have been attached to the Board (such as Power-Ups).

Important Methods

GET /1/members/me/boards - Get an array of the Boards of a user
GET /1/boards/[board_id]/cards - Get an array of Cards on a board
GET /1/boards/[board_id]/lists - Get an array of Lists on a board

Lists

Full Lists Reference
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

Full Cards API Reference
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

Full Actions API Reference
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

Full Webhooks API Reference

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

Learn more about Webhooks

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.

Intro to client.js

Follow this guide to start building an integration with Trello using client.js. We'll only be using javascript and you should be able to run this locally via a static HTML page.

The client.js library was created to make it easier to use the Trello REST API with web applications. There's nothing magic about it, but it can make things a little bit faster through some convenient methods.

There are two steps to using the client.js library. The first is to get your Application Key. This Key identifies your Application to the API and is needed for any authenticated or unauthenticated API Calls.

Get your Application Key

Now we can include jQuery and the client.js library on the page. Before the body tag, add the following and replace the {APIKey} with the API key you just retrieved:

<script src="http://code.jquery.com/jquery-1.7.1.min.js"></script>
<script src="https://api.trello.com/1/client.js?key={APIKey}"></script>

Now that you have included these two dependencies, you will have access to a global Trello object that has many helper methods. Next up, we'll authenticate our user so that we can access data in Trello on their behalf.

Authenticate Your User

Using the Trello object, we need to authenticate the user. This is done with the Trello.authenticate method. This method will automatically trigger Trello's authorization flow and return back an authentication token. This token will be specific to your API key and the user who is executing the flow.

It's important to understand that the authentication token gives your application the ability to make calls on behalf of your user, from their context. This token grants access to the authenticated user's boards, lists, cards, and other settings, depending on the permissions requested in the authenticate method.

We now have the ability to access our user's Trello data. The functionality provided via client.js makes use of callbacks for success and failure. We can create some basic methods to get started.

First, let's define what happens when authentication has finished using success and failure callbacks.

var authenticationSuccess = function() {
  console.log('Successful authentication');
};

var authenticationFailure = function() {
  console.log('Failed authentication');
};

Now let's attempt authentication and authorization in one step:

window.Trello.authorize({
  type: 'popup',
  name: 'Getting Started Application',
  scope: {
    read: 'true',
    write: 'true' },
  expiration: 'never',
  success: authenticationSuccess,
  error: authenticationFailure
});

If authentication was successful, the Trello object will now store and use our valid Authentication Token for all future calls. Handy!

Create Cards and Update Information

We are now ready to make any API call that we would like using the context of both our application (defined by our API key), and a user (defined by the authentication token).

One of the trickier parts of using the Trello API for simple use cases is finding a List ID that belongs to a user. There are a few ways of doing this depending on your skillsets. One such way is to use the Chrome Dev Tools to watch network traffic from the official client.

To try to make this easy, we'll be dumping the JSON from a known Card. Open the official Trello web client and find a Card from a list that you want to use as your target.

It should have a short URL that looks like:
https://trello.com/c/DcqBrqdx/1-target-card

Take that URL and add .json to the end as follows:
https://trello.com/c/DcqBrqdx/1-target-card.json

Within the raw JSON dump you get when pulling up this new URL, you will see a field called idList. We're about to use this to create a new Card in the same list.

Creating a Card is one of the simplest API calls you can make. We just create a Card object that contains the parameters we want to set, and then POST it to the API.

var myList = 'INSERT YOUR IDLIST HERE';

var creationSuccess = function (data) {
  console.log('Card created successfully.');
  console.log(JSON.stringify(data, null, 2));
};

var newCard = {
  name: 'New Test Card', 
  desc: 'This is the description of our new card.',
  // Place this card at the top of our list 
  idList: myList,
  pos: 'top'
};

window.Trello.post('/cards/', newCard, creationSuccess);

Now that we have created a card and retrieved its ID via the log, we're going to make an update to this card. To do so, we will PUT a new name for it.

window.Trello.put('/cards/[ID]', {name: 'New Test Card'});

API Introduction

A walkthrough of getting started with Trello's RESTful API, making your first request, and an overview of the most important Trello resources!