client.js Reference

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:

Key	Values	Description
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: true	If true, the token will be saved to local storage.
interactive boolean	Default: true	If 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)

Key	Values	Description
method string	One of: `GET`, `POST`, `PUT`, `DELETE`	HTTP 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.

Option	Description
url	Required URL you would like to share
mode	Currently only "popup" is supported
source	The originating URL of your request
name	The name that you want to give the card
idList	The ID of the List where you want to add the new card
idBoard	The ID of the Board where you want to add the new card
width	The width in pixels of the popup
height	The height in pixels of the popup
left	The distance from the left edge of the user's screen in pixels for the popup
top	The 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

Key	Description
source	The originating URL of your request.
name	The name that you want to give the card
idList	The ID of the List where you want to add the new card
idBoard	The ID of the Board where you want to add the new card