Last updated Dec 16, 2019

We've put together a small javascript library to make it easier to interact with Trello's API in your applications. It provides a global Trello object that includes helper methods for common actions in Trello's API. You can find the full source code for client.js.

For a tutorial on using client.js, check out Getting Started with client.js.

client.js requires jQuery as a dependency.

By adding the following to your page, a global Trello object will be available with many useful methods. By specifying your API Key in the URL for client.js, we will automatically use it when we make requests.

1
2
<script src="https://trello.com/1/client.js?key=[key]"></script>

Authorizing

Call Trello.authorize(opts) with the following options:

KeyValuesDescription
type
string
One of: redirect or popup
Default: redirect
Whether authorization should be done in a new window, or by leaving the current page
name
string
Name of your application, which is displayed during the authorization process
persist
boolean
Default: trueIf true, the token will be saved to local storage.
interactive
boolean
Default: trueIf false, don’t redirect or popup, only use the stored token.
scope
object
Default is read-only, i.e. { read: true, write: false, account: false }Each permission is a boolean. { read: allowRead, write: allowWrite, account: allowAccount }
expiration
string
One of: 1hour, 1day, 30days, or never
Default: 30days
When the token should expire.
success
function
Optional function to be called on success.
error
function
Optional function to be called on error.
If using type: redirect, the token will be returned to the current location.href. When it is returned, call authorize with interactive: false to get the token.

Using the API

You can use the API via a single call:

window.Trello.rest(method, path[, params], success, error)

KeyValuesDescription
method
string
One of: GET, POST, PUT, DELETEHTTP method to use when making the request to the Trello API.
path
string
Valid Trello API path without prepended /1/.API path to use, such as "members/me"
params
object
Default: {}Query parameters to the API path, such as { fields: "username,fullName" }
success
function
Optional function to be called on success.
error
function
Optional function to be called on error

There are also a number of convenience methods, with similar signatures. One for each HTTP method:

1
2
Trello.get(path[, params], success, error)
Trello.post(path[, params], success, error)
Trello.put(path[, params], success, error)
Trello.delete(path[, params], success, error)

An alias for delete: Trello.del(path[, params], success, error)

And one for GETting on each collection:

1
2
Trello.actions.get(id[, params], success, error)
Trello.cards.get(id[, params], success, error)
Trello.checklists.get(id[, params], success, error)
Trello.boards.get(id[, params], success, error)
Trello.lists.get(id[, params], success, error)
Trello.members.get(id[, params], success, error)
Trello.organizations.get(id[, params], success, error)

Add Card UI

Another capability of the client.js library is the ability to create cards directly into a Trello member's account without needing to authenticate. This functions similarly to Facebook's support for sharing URLs. When using this capability, you do not get access to the user's account, and no authorization step is required.

This method takes a required Options object, and an optional callback URL. If no callback URL is provided, the method will attempt to return a promise, if supported by the current browser.

OptionDescription
urlRequired URL you would like to share
modeCurrently only "popup" is supported
sourceThe originating URL of your request
nameThe name that you want to give the card
idListThe ID of the List where you want to add the new card
idBoardThe ID of the Board where you want to add the new card
widthThe width in pixels of the popup
heightThe height in pixels of the popup
leftThe distance from the left edge of the user's screen in pixels for the popup
topThe distance from the top edge of the user's screen in pixels for the popup

Once you have included client.js on your page, you can call:

window.Trello.addCard({url:'http://example.com'});

This will create a popup that will share the specified URL.

Using URL Parameters

You can also achieve this functionality directly via its URL. By taking a member to a specially constructed URL, the Trello member will be able to make a choice regarding his or her boards and lists, and be able to decide where to store the new card and URL that is being shared.

The URL looks like this:

https://trello.com/add-card?url=https://developer.atlassian.com/cloud/trello&name=Trello%20Developers

KeyDescription
sourceThe originating URL of your request.
nameThe name that you want to give the card
idListThe ID of the List where you want to add the new card
idBoardThe ID of the Board where you want to add the new card

Rate this page: