What we do
Tools
Industries
Department
How we workLet's talk →
Home/Trello/Trello API
Trello

The Trello API: Get a Key and Token, Create a Card, Listen for Changes

Trello's REST API reads and writes the same boards, lists, cards and members you see in the app. You need two things: an API key, which identifies your app, and a token, which acts as a Trello user. With both, a first request is one line of curl.

Get access

API key: create a Power-Up in Trello's admin portal (trello.com/apps/admin), open it, go to the Trello Auth tab and click Generate a new API Key. The key is meant to be public and grants nothing on its own.

trello.com/apps/admin Your Power-Up Trello Auth Generate a new API Key

Token: click the Token link next to the key and click Allow. The token can read and write that user's whole Trello account, so keep it secret.

First call: curl 'https://api.trello.com/1/members/me/boards?key=KEY&token=TOKEN' returns every board the token's user can see. me means the token's owner.

Trello API rate limits

The limits are per API key and per token, not per Trello plan. Going over returns a 429.

Limit Allowance What it means for you
Per API key 300 requests every 10 seconds Shared by every token on that key. One busy customer's sync can slow everyone else's.
Per token 100 requests every 10 seconds Set lower so a single runaway token can't use up the whole key.
/1/members/ endpoints 100 requests every 900 seconds Much tighter. Cache member lookups instead of fetching them on every card.
Webhooks No cap on how many you register Usually the cheapest way to stay inside the request limits, compared with polling boards on a timer.

Create a card in the right list

The most common first job: something happens elsewhere, and a card should appear on a board.

  1. 1

    Find the list ID

    Call GET /1/boards/{boardId}/lists to get the lists on a board with their IDs. The short code in a board's URL works as the board ID here.

  2. 2

    Create the card

    POST /1/cards with idList, name and optionally desc, due, idMembers and idLabels. The response is the new card, including its ID.

    Watch for: send the key and token as query parameters, in the body, or in a header: Authorization: OAuth oauth_consumer_key="KEY", oauth_token="TOKEN". The header keeps the token out of server logs.

  3. 3

    Set custom fields separately

    Custom field values aren't part of the card create call. Look up the board's fields with GET /1/boards/{boardId}/customFields, then set each value on the card with its own PUT to the card's custom field item.

  4. 4

    Make a token for production, not your own

    For anything that runs unattended, authorize through the /1/authorize route with only the scope you need (read, write, account) and an expiration of 1hour, 1day, 30days or never. Tie it to a service account, not a person who might leave. Trello also supports OAuth 2.0 for apps acting for many users.

Why Trello webhooks fail, vanish or fire twice

Register one with POST /1/tokens/{token}/webhooks, passing callbackURL and idModel (a board, card, member or Workspace ID).

The webhook won't create

How you'll know: The create call fails even though your endpoint works.

Fix: Trello sends a HEAD request to the callback URL first and needs a 200 back. Many frameworks only route POST. Answer HEAD too, and make sure nothing like a login wall or proxy sits in front of it.

It worked for a month, then disappeared

How you'll know: No more events, and the webhook no longer shows up for the token.

Fix: A webhook belongs to the token that made it. If that token expires (a 30days token, say) or is revoked, the webhook is deleted with it. Use a long-lived service token, and check your registrations on a schedule.

The same change arrives twice

How you'll know: Your handler created two records for one card move.

Fix: When a delivery fails, Trello retries up to three times: after 30, 60 and 120 seconds. A slow handler can get a retry while it's still working. Reply quickly, do the work afterwards, and skip any action ID you've already processed.

Signatures don't match

How you'll know: Your check of the X-Trello-Webhook header rejects real requests.

Fix: It's a base64 HMAC-SHA1 of the raw request body plus the callback URL exactly as you registered it, signed with your app secret. A trailing slash or a re-serialized body breaks it.

Your endpoint was down for days

How you'll know: Events from the outage never arrive.

Fix: Retries stop after the third try, so those events are gone. Re-read the affected boards with the API to catch up. Trello only disables a webhook after 30 days and more than 1,000 failures in a row, and replying 410 Gone deletes it on purpose.

What keeps a Trello integration working after launch

The first card is easy. What breaks later is quieter: a token tied to someone who left, a webhook deleted with it, a member lookup that hits its 900-second limit on a busy morning, a retry that creates a duplicate invoice. None of it shows up as an error on the board. Cards just stop appearing.

n-frames builds and runs this layer for teams that don't want it on a developer's side list: the webhook listener, the de-duplication, a check that re-registers webhooks before they lapse, and an alert when something stops. Every Power-Up and integration is built on this same API, so anything one does, a direct integration can do without installing it.

Questions people ask

Is the Trello API free to use?

Yes. There's no paid API tier. You need an API key and a token, and every key and token gets the same request limits, whatever Trello plan the boards are on.

Do I need to know how to code to use the Trello API?

Yes, at least enough to send HTTP requests from a script or an app. If you'd rather have the result without owning the code, that's the part n-frames builds and maintains.

What can I build with the Trello API?

Anything that reads or writes board data: cards created from forms, orders or leads; card status synced with a CRM or helpdesk; reports pulled across many boards; a client-facing status page that doesn't need a Trello login. The Trello and Jira integration is one common example.

Does Trello have webhooks?

Yes. Register a webhook against a board, card, member or Workspace, and Trello POSTs the action and the changed model to your URL as soon as something changes. There's no limit on how many you set up.

What does a 429 error from the Trello API mean?

You've gone over a rate limit: 300 requests per 10 seconds per key, 100 per 10 seconds per token, or the tighter limit on member endpoints. Back off and retry, read the remaining-quota headers on each response, and swap polling for webhooks where you can.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.