A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Trello API is how an app or AI agent works with a Trello workspace: reading the boards, lists, and cards a user can see, creating and moving cards, commenting, and watching for changes. Access is granted through an API key that identifies the application and a user token that represents one person, and the token carries scopes, read, write, and account, that set what a call may do. A token reaches only the boards and organizations its member can already see, so scope and membership together draw the boundary, and Trello can post a change to a registered webhook.
How an app or AI agent connects to Trello determines what it can reach. A call carries an API key that identifies the application and a token that represents one user, and the token's scopes and that user's board memberships set the boundary of what the call can read or change.
The REST API is served from https://api.trello.com/1, returns JSON, and selects fields with a fields query parameter. A call passes an API key and a user token, either as key and token query parameters or in an Authorization header as OAuth oauth_consumer_key and oauth_token. The route accepts both singular and plural nouns, so /1/members/me and /1/member/me are equivalent.
Trello POSTs a JSON payload to a registered callback URL when a watched model changes, carrying the action, the updated model, and the webhook itself. A webhook is tied to one token and one model id, and a token's webhook is removed when the token expires. Each delivery includes an X-Trello-Webhook header, a base64 HMAC-SHA1 digest of the request body concatenated with the callback URL, so a receiver can confirm the request came from Trello. A webhook that fails for 30 days is disabled.
An API key identifies the application and is tied to a Power-Up; it is acceptable for the key to be public. A user token represents one Trello user and grants access to their account, so it must be kept secret. The token carries scopes (read, write, account) and an expiry chosen at authorization (1hour, 1day, 30days, or never), and a call sends both the key and the token.
An application sends a user to the /1/authorize route with its API key, the requested scopes, and an expiration, and Trello returns a user token after the user approves. This is the simpler of the two token-granting flows and is used by many client-side integrations.
Trello supports the standard OAuth 1.0a flow to obtain a user token, with the same read, write, and account scopes. Trello has announced it is moving to OAuth 2.0 (3LO) through Forge, which will add new scopes, resource restrictions, and token expiry.
The Trello API is split into the objects an agent can act on, like boards, lists, cards, and members. Each object has its own methods, and a token reaches only the boards and organizations the user behind it can already see.
Methods for working with boards, the top-level container for lists and cards.
Methods for working with lists, the columns that hold cards on a board.
Methods for working with cards, the individual items on a list.
Methods for reading and updating members, the people in Trello.
Methods for registering and managing webhooks that watch a model for changes.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
BoardsMethods for working with boards, the top-level container for lists and cards.7 | ||||||
| GET | /1/boards/{id} | Retrieve a single board by id. | read | read | Current | |
Needs the read scope; the token must belong to a member who can see the board. Acts onboard Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/boards/ | Create a new board. | write | write | Current | |
Needs the write scope. Acts onboard Permission (capability) writeVersionAvailable since the API’s base version Webhook event createBoardRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /1/boards/{id} | Update an existing board, such as its name, description, or open/closed state. | write | write | Current | |
Needs the write scope. Acts onboard Permission (capability) writeVersionAvailable since the API’s base version Webhook event updateBoardRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /1/boards/{id} | Permanently delete a board. | write | write | Current | |
Needs the write scope; the deletion is irreversible and removes the board's lists and cards. Acts onboard Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1/boards/{id}/lists | Get the lists on a board. | read | read | Current | |
Needs the read scope. Acts onlist Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1/boards/{id}/cards | Get the cards on a board. | read | read | Current | |
Needs the read scope; a request for too many cards at once can return API_TOO_MANY_CARDS_REQUESTED. Acts oncard Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1/boards/{id}/members | Get the members of a board. | read | read | Current | |
Needs the read scope. Acts onmember Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ListsMethods for working with lists, the columns that hold cards on a board.5 | ||||||
| GET | /1/lists/{id} | Retrieve a single list by id. | read | read | Current | |
Needs the read scope. Acts onlist Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/lists | Create a new list on a board. | write | write | Current | |
Needs the write scope. Acts onlist Permission (capability) writeVersionAvailable since the API’s base version Webhook event createListRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /1/lists/{id} | Update a list, such as its name or position. | write | write | Current | |
Needs the write scope. Acts onlist Permission (capability) writeVersionAvailable since the API’s base version Webhook event updateListRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /1/lists/{id}/closed | Archive or unarchive a list by setting its closed state. | write | write | Current | |
Needs the write scope; archiving keeps the list and its cards rather than deleting them. Acts onlist Permission (capability) writeVersionAvailable since the API’s base version Webhook event updateListRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1/lists/{id}/cards | Get the cards in a list. | read | read | Current | |
Needs the read scope. Acts oncard Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CardsMethods for working with cards, the individual items on a list.5 | ||||||
| GET | /1/cards/{id} | Retrieve a single card by id. | read | read | Current | |
Needs the read scope. Acts oncard Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/cards | Create a new card on a list. | write | write | Current | |
Needs the write scope; the list it is created on must be on a board the token can write to. Acts oncard Permission (capability) writeVersionAvailable since the API’s base version Webhook event createCardRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /1/cards/{id} | Update a card, such as its name, description, due date, or the list it sits on. | write | write | Current | |
Needs the write scope; moving a card between lists is an update to its idList. Acts oncard Permission (capability) writeVersionAvailable since the API’s base version Webhook event updateCardRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /1/cards/{id} | Permanently delete a card. | write | write | Current | |
Needs the write scope; the deletion is irreversible, unlike archiving. Acts oncard Permission (capability) writeVersionAvailable since the API’s base version Webhook event deleteCardRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/cards/{id}/actions/comments | Add a comment to a card. | write | write | Current | |
Needs the write scope; the comment is attributed to the member behind the token. Acts onaction Permission (capability) writeVersionAvailable since the API’s base version Webhook event commentCardRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MembersMethods for reading and updating members, the people in Trello.4 | ||||||
| GET | /1/members/{id} | Retrieve a member by id or username. | read | read | Current | |
Needs the read scope; member endpoints are limited to 100 requests per 900 seconds. Acts onmember Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limit100 requests / 900s on /1/members/ SourceOfficial documentation ↗ | ||||||
| GET | /1/members/me | Retrieve the member behind the token, the authenticated user. | read | read | Current | |
Needs the read scope; reading the member's email also requires the account scope. Acts onmember Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limit100 requests / 900s on /1/members/ SourceOfficial documentation ↗ | ||||||
| GET | /1/members/{id}/boards | Get the boards a member belongs to. | read | read | Current | |
Needs the read scope; member endpoints are limited to 100 requests per 900 seconds. Acts onboard Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limit100 requests / 900s on /1/members/ SourceOfficial documentation ↗ | ||||||
| PUT | /1/members/{id} | Update a member's information, such as their full name, bio, or username. | write | account | Current | |
Writing member info needs the account scope, which also covers reading a member's email and marking notifications read. Acts onmember Permission (capability) accountVersionAvailable since the API’s base version Webhook eventNone Rate limit100 requests / 900s on /1/members/ SourceOfficial documentation ↗ | ||||||
WebhooksMethods for registering and managing webhooks that watch a model for changes.4 | ||||||
| POST | /1/webhooks/ | Create a webhook that watches a model id and POSTs changes to a callback URL. | write | read | Current | |
The webhook belongs to the token and can only watch models that token can access; the read scope is enough to receive change notifications. Acts onwebhook Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1/webhooks/{id} | Retrieve a webhook by id. | read | read | Current | |
Needs the read scope; the webhook must belong to the token used. Acts onwebhook Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /1/webhooks/{id} | Update a webhook, such as its callback URL, watched model, or active state. | write | read | Current | |
The webhook must belong to the token used, or the call returns a 'webhook does not belong to token' error. Acts onwebhook Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /1/webhooks/{id} | Delete a webhook so it no longer fires. | write | read | Current | |
The webhook must belong to the token used; webhooks are also removed automatically when their token expires. Acts onwebhook Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Trello can notify an app or AI agent when a watched object changes, like a card being moved or a comment being added, instead of the app polling for changes. A webhook is attached to a token and a single model id, and Trello POSTs the action and the updated model to a registered callback URL.
| Event | What it signals | Triggered by |
|---|---|---|
createCard | A card was created on a board or list the webhook watches. | /1/cards |
updateCard | A card changed, like its name, description, due date, or the list it sits on. Moving a card fires this event. | /1/cards/{id} |
deleteCard | A card was permanently deleted. | /1/cards/{id} |
commentCard | A comment was added to a card. | /1/cards/{id}/actions/comments |
createList | A list was created on a board the webhook watches. | /1/lists |
updateList | A list changed, like its name, position, or open/closed state. | /1/lists/{id}/1/lists/{id}/closed |
createBoard | A board was created. | /1/boards/ |
updateBoard | A board changed, like its name, description, or open/closed state. | /1/boards/{id} |
Trello limits how fast an app or AI agent can call, by a per-key rate and a separate per-token rate measured over a ten-second window, with a tighter limit on member endpoints.
Trello meters requests two ways at once: 300 requests per 10 seconds for each API key, and 100 requests per 10 seconds for each token. The /1/members/ endpoints carry a tighter limit of 100 requests per 900 seconds. Going over returns HTTP 429 with an error of API_KEY_LIMIT_EXCEEDED or API_TOKEN_LIMIT_EXCEEDED, and if a single key accumulates more than 200 of these 429s, Trello returns 429 for the rest of that key's requests. Every response carries x-rate-limit headers giving the interval, the max, and the remaining count for both the key and the token, so an integration can pace itself.
Most list endpoints return the full set for the parent object rather than a numbered page, and a limit parameter caps how many items come back (for example up to 1000 actions on a board). Time-ordered endpoints like actions accept before and since parameters that take an id or date to walk through history. Requesting too much at once, such as all cards with their actions, can return API_TOO_MANY_CARDS_REQUESTED.
A token's webhook is removed when the token expires, and a webhook that fails to deliver for 30 days is disabled. A token's expiry is set at authorization to 1hour, 1day, 30days, or never. The fields parameter trims a response to named fields, with the object id always returned.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed, like a missing required parameter or an invalid value. | Read the error message, fix the parameters, and resend. The request is not retryable as-is. |
| 401 | Unauthorized | The API key or token is missing, invalid, or expired, or the token lacks the scope the request needs. | Confirm both the key and a current token are sent, and that the token carries the read, write, or account scope the call requires. |
| 404 | Not Found | The object does not exist, or is not visible to the member behind the token. | Verify the id and confirm the token's member has access to it. |
| 429 | API_KEY_LIMIT_EXCEEDED / API_TOKEN_LIMIT_EXCEEDED | The per-key (300 per 10s) or per-token (100 per 10s) rate was exceeded; a sustained excess of 429s on a key returns 429 for the rest of that key's requests. | Back off and retry, reading the x-rate-limit headers to pace requests, and smooth bursts across the ten-second window. |
Trello's REST API carries a single path version, 1, and ships dated changes through its developer changelog rather than minting new version numbers.
Trello's REST API is served under https://api.trello.com/1 and carries no version numbers beyond the path 1. Changes ship through the developer changelog rather than new version strings, so the entries below are the notable recent dated changes.
Atlassian published new security requirements for Government Cloud apps effective 31 March 2026, plus annual updates to its Cloud App Security Requirements covering AI security, data protection, and runtime security.
The SCIM endpoints /scim/v2/users and /scim/v2/groups were announced for deprecation on or after 10 December 2025, in favour of the REST API for Trello members and related queries.
Trello announced that OAuth 2.0 will replace its current authorization mechanism, introducing new scopes, resource restrictions, and token expiry, with external OAuth2 clients using Forge's OAuth2 Providers as confidential clients.
The PUT /1/boards/{id}/labelNames endpoint was announced for deprecation in six months (around 18 August 2025), with developers directed to the label creation and update endpoints instead.
There is one live version of the REST API; track the changelog for deprecations.
Trello developer changelog ↗Bollard AI sits between a team's AI agents and Trello. Grant each agent exactly the access it needs, read or write, board by board, and every call is checked and logged.