Trello Developers

client.js

Learn about using client.js in our Getting Started Guide. You can also find the full source code for client.js in its original CoffeeScript.

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.

<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.

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
string

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:

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:

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

Another capability of the client.js library is the ability to share URLs 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://developers.trello.com/&name=Trello%20Developers
Key
Description

source

The originating URL of your request.

name

The name that you want to give the card

idList

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

client.js