Skip to main content

Actions

The ballerinax/trello package exposes the following clients:

ClientPurpose
ClientTrello REST API: boards, lists, cards, members, labels, checklists, search, webhooks.

Client

Trello REST API: boards, lists, cards, members, labels, checklists, search, webhooks.

Configuration

FieldTypeDefaultDescription
apiKeyConfigApiKeysConfigRequiredAPI key and token configuration containing key and token fields.
configConnectionConfig{}HTTP client connection configuration.
serviceUrlstring"https://api.trello.com/1"Base URL for the Trello API.

Initializing the client

import ballerinax/trello;

configurable string apiKey = ?;
configurable string apiToken = ?;

trello:Client trello = check new ({
key: apiKey,
token: apiToken
});

Operations

Boards

Get a Board

Retrieves a board by its Trello ID.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the board.

Returns: Board|error

Sample code:

trello:Board board = check trello->/boards/[boardId];

Sample response:

{"id": "60d5f2c8e4b0a12345678901", "name": "My Project Board", "desc": "Board for tracking tasks", "closed": false, "url": "https://trello.com/b/abc123/my-project-board"}
Create Board

Creates a new board.

Parameters:

NameTypeRequiredDescription
queriesPostBoardsQueriesYesQuery parameters including name (required), defaultLabels, defaultLists, desc, idOrganization, and more.

Returns: error?

Sample code:

_ = check trello->/boards.post(queries = {name: "New Project Board"});
Update a Board

Updates a board's properties such as name, description, or closed status.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the board.
queriesPutBoardsIdQueriesNoQuery parameters for fields to update.

Returns: error?

Sample code:

_ = check trello->/boards/[boardId].put(queries = {name: "Updated Board Name", desc: "New description"});
Delete a Board

Permanently deletes a board.

Parameters:

NameTypeRequiredDescription
idstringYesThe ID of the board.

Returns: error?

Sample code:

_ = check trello->/boards/[boardId].delete();
Get Lists on a Board

Retrieves all lists on a board.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the board.

Returns: TrelloList[]|error

Sample code:

trello:TrelloList[] lists = check trello->/boards/[boardId]/lists;

Sample response:

[{"id": "60d5f2c8e4b0a12345678902", "name": "To Do", "closed": false, "pos": 16384, "idBoard": "60d5f2c8e4b0a12345678901"}, {"id": "60d5f2c8e4b0a12345678903", "name": "In Progress", "closed": false, "pos": 32768, "idBoard": "60d5f2c8e4b0a12345678901"}]
Create a List on a Board

Creates a new list on a board.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the board.
queriesPostBoardsIdListsQueriesYesQuery parameters including name (required) and pos.

Returns: TrelloList|error

Sample code:

trello:TrelloList newList = check trello->/boards/[boardId]/lists.post(queries = {name: "Done"});

Sample response:

{"id": "60d5f2c8e4b0a12345678904", "name": "Done", "closed": false, "pos": 49152, "idBoard": "60d5f2c8e4b0a12345678901"}
Get the Members of a Board

Retrieves all members of a board.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the board.

Returns: error?

Sample code:

_ = check trello->/boards/[boardId]/members;
Get Labels on a Board

Retrieves all labels on a board.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the board.

Returns: error?

Sample code:

_ = check trello->/boards/[boardId]/labels;
Create a Label on a Board

Creates a new label on a board.

Parameters:

NameTypeRequiredDescription
idstringYesThe ID of the board.
queriesPostBoardsIdLabelsQueriesYesQuery parameters including name and color.

Returns: error?

Sample code:

_ = check trello->/boards/[boardId]/labels.post(queries = {name: "Urgent", color: "red"});
Get Custom Fields for Board

Retrieves all custom field definitions on a board.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the board.

Returns: CustomField[]|error

Sample code:

trello:CustomField[] fields = check trello->/boards/[boardId]/customFields;

Sample response:

[{"id": "60d5f2c8e4b0a12345678910", "idModel": "60d5f2c8e4b0a12345678901", "name": "Priority", "type": "list", "pos": 1}]

Lists

Get a List

Retrieves a list by its ID.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the list.

Returns: TrelloList|error

Sample code:

trello:TrelloList list = check trello->/lists/[listId];

Sample response:

{"id": "60d5f2c8e4b0a12345678902", "name": "To Do", "closed": false, "pos": 16384, "idBoard": "60d5f2c8e4b0a12345678901"}
Update a List

Updates a list's properties such as name, position, or closed status.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the list.
queriesPutListsIdQueriesNoQuery parameters for fields to update.

Returns: error?

Sample code:

_ = check trello->/lists/[listId].put(queries = {name: "Completed"});
Get Cards in a List

Retrieves all cards in a list.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the list.

Returns: Card[]|error

Sample code:

trello:Card[] cards = check trello->/lists/[listId]/cards;

Sample response:

[{"id": "60d5f2c8e4b0a12345678905", "name": "Design mockups", "desc": "Create UI mockups", "closed": false, "idList": "60d5f2c8e4b0a12345678902", "pos": 16384}]
Archive all Cards in a List

Archives all cards in the specified list.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the list.

Returns: error?

Sample code:

_ = check trello->/lists/[listId]/archiveAllCards.post();
Move all Cards in a List

Moves all cards in a list to another board and/or list.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the list.
queriesPostListsIdMoveallcardsQueriesYesQuery parameters including target idBoard and idList.

Returns: error?

Sample code:

_ = check trello->/lists/[listId]/moveAllCards.post(queries = {idBoard: targetBoardId, idList: targetListId});
Get Board of a List

Retrieves the board that a list belongs to.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the list.

Returns: Board|error

Sample code:

trello:Board board = check trello->/lists/[listId]/board;

Sample response:

{"id": "60d5f2c8e4b0a12345678901", "name": "My Project Board", "closed": false}

Cards

Create a new Card

Creates a new card on a specified list.

Parameters:

NameTypeRequiredDescription
queriesPostCardsQueriesYesQuery parameters including idList (required), name, desc, pos, due, idMembers, idLabels, and more.

Returns: Card|error

Sample code:

trello:Card card = check trello->/cards.post(queries = {
idList: listId,
name: "Implement login feature",
desc: "Add OAuth 2.0 login support"
});

Sample response:

{"id": "60d5f2c8e4b0a12345678905", "name": "Implement login feature", "desc": "Add OAuth 2.0 login support", "closed": false, "idList": "60d5f2c8e4b0a12345678902", "url": "https://trello.com/c/xyz789"}
Get a Card

Retrieves a card by its ID.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the card.

Returns: Card|error

Sample code:

trello:Card card = check trello->/cards/[cardId];

Sample response:

{"id": "60d5f2c8e4b0a12345678905", "name": "Implement login feature", "desc": "Add OAuth 2.0 login support", "closed": false, "idList": "60d5f2c8e4b0a12345678902", "pos": 16384, "due": "2026-04-01T12:00:00.000Z"}
Update a Card

Updates a card's properties such as name, description, due date, or list assignment.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the card.
queriesPutCardsIdQueriesNoQuery parameters for fields to update.

Returns: Card|error

Sample code:

trello:Card updated = check trello->/cards/[cardId].put(queries = {name: "Updated card name"});

Sample response:

{"id": "60d5f2c8e4b0a12345678905", "name": "Updated card name", "closed": false, "idList": "60d5f2c8e4b0a12345678902"}
Delete a Card

Permanently deletes a card.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the card.

Returns: TrelloList|error

Sample code:

_ = check trello->/cards/[cardId].delete();
Get Actions on a Card

Retrieves the actions (activity history) on a card.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the card.

Returns: Action[]|error

Sample code:

trello:Action[] actions = check trello->/cards/[cardId]/actions;

Sample response:

[{"id": "60d5f2c8e4b0a12345678920", "type": "updateCard", "date": "2026-03-15T10:30:00.000Z", "idMemberCreator": "60d5f2c8e4b0a12345678930"}]
Get Attachments on a Card

Retrieves all attachments on a card.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the card.

Returns: InlineResponseItems2001[]|error

Sample code:

trello:InlineResponseItems2001[] attachments = check trello->/cards/[cardId]/attachments;

Sample response:

[{"id": "60d5f2c8e4b0a12345678940", "name": "design.png", "url": "https://trello.com/1/cards/abc/attachments/xyz/download/design.png", "bytes": 204800}]
Create Attachment On Card

Creates an attachment on a card.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the card.
queriesPostCardsIdAttachmentsQueriesNoQuery parameters including name, url, mimeType.

Returns: InlineResponseItems2002[]|error

Sample code:

trello:InlineResponseItems2002[] attachment = check trello->/cards/[cardId]/attachments.post(
queries = {name: "Reference Doc", url: "https://example.com/doc.pdf"}
);

Sample response:

[{"id": "60d5f2c8e4b0a12345678941", "name": "Reference Doc", "url": "https://example.com/doc.pdf"}]
Add a new comment to a Card

Adds a comment to a card.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the card.
queriesPostCardsIdActionsCommentsQueriesYesQuery parameters including text (required).

Returns: Action|error

Sample code:

trello:Action comment = check trello->/cards/[cardId]/actions/comments.post(
queries = {text: "This task is now in review."}
);

Sample response:

{"id": "60d5f2c8e4b0a12345678950", "type": "commentCard", "date": "2026-03-17T08:00:00.000Z", "data": {"text": "This task is now in review."}}
Add a Label to a Card

Adds an existing label to a card.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the card.
queriesPostCardsIdIdlabelsQueriesYesQuery parameters including value (the label ID).

Returns: error?

Sample code:

_ = check trello->/cards/[cardId]/idLabels.post(queries = {value: labelId});
Add a Member to a Card

Adds a member to a card.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the card.
queriesPostCardsIdIdmembersQueriesYesQuery parameters including value (the member ID).

Returns: error?

Sample code:

_ = check trello->/cards/[cardId]/idMembers.post(queries = {value: memberId});
Get Custom Field Items for a Card

Retrieves all custom field values set on a card.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the card.

Returns: CustomFieldItems[]|error

Sample code:

trello:CustomFieldItems[] items = check trello->/cards/[cardId]/customFieldItems;

Sample response:

[{"id": "60d5f2c8e4b0a12345678960", "idCustomField": "60d5f2c8e4b0a12345678910", "idModel": "60d5f2c8e4b0a12345678905", "value": {"text": "High"}}]

Checklists

Create a Checklist

Creates a new checklist.

Parameters:

NameTypeRequiredDescription
queriesPostChecklistsQueriesYesQuery parameters including idCard (required), name, pos, idChecklistSource.

Returns: error?

Sample code:

_ = check trello->/checklists.post(queries = {idCard: cardId, name: "Launch Checklist"});
Get a Checklist

Retrieves a checklist by its ID.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the checklist.

Returns: error?

Sample code:

_ = check trello->/checklists/[checklistId];
Get Checkitems on a Checklist

Retrieves all check items on a checklist.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the checklist.

Returns: error?

Sample code:

_ = check trello->/checklists/[checklistId]/checkItems;
Create Checkitem on Checklist

Creates a new check item on a checklist.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the checklist.
queriesPostChecklistsIdCheckitemsQueriesYesQuery parameters including name (required), pos, checked.

Returns: error?

Sample code:

_ = check trello->/checklists/[checklistId]/checkItems.post(queries = {name: "Write unit tests"});
Delete Checkitem from Checklist

Deletes a check item from a checklist.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the checklist.
idCheckItemTrelloIDYesThe ID of the check item.

Returns: error?

Sample code:

_ = check trello->/checklists/[checklistId]/checkItems/[checkItemId].delete();

Labels

Get a Label

Retrieves a label by its ID.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the label.

Returns: Label|error

Sample code:

trello:Label label = check trello->/labels/[labelId];

Sample response:

{"id": "60d5f2c8e4b0a12345678970", "name": "Urgent", "color": "red", "idBoard": "60d5f2c8e4b0a12345678901"}
Update a Label

Updates a label's name or color.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the label.
queriesPutLabelsIdQueriesNoQuery parameters for fields to update.

Returns: error?

Sample code:

_ = check trello->/labels/[labelId].put(queries = {name: "Critical", color: "red"});
Delete a Label

Deletes a label.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the label.

Returns: error?

Sample code:

_ = check trello->/labels/[labelId].delete();

Members

Get a Member

Retrieves a member by their ID.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the member.

Returns: Member|error

Sample code:

trello:Member member = check trello->/members/[memberId];

Sample response:

{"id": "60d5f2c8e4b0a12345678930", "fullName": "Jane Smith", "username": "janesmith", "email": "[email protected]"}
Get Member (authenticated)

Retrieves the authenticated member's profile.

Returns: Member|error

Sample code:

trello:Member me = check trello->/members/me;

Sample response:

{"id": "60d5f2c8e4b0a12345678930", "fullName": "Jane Smith", "username": "janesmith", "email": "[email protected]"}
Get Boards a Member belongs to

Retrieves all boards a member belongs to.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the member.

Returns: Board[]|error

Sample code:

trello:Board[] boards = check trello->/members/[memberId]/boards;

Sample response:

[{"id": "60d5f2c8e4b0a12345678901", "name": "My Project Board", "closed": false}]
Get Cards a Member is on

Retrieves all cards assigned to a member.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the member.

Returns: Card[]|error

Sample code:

trello:Card[] cards = check trello->/members/[memberId]/cards;

Sample response:

[{"id": "60d5f2c8e4b0a12345678905", "name": "Implement login feature", "idList": "60d5f2c8e4b0a12345678902"}]
Get Member's Organizations

Retrieves all organizations a member belongs to.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the member.

Returns: Organization[]|error

Sample code:

trello:Organization[] orgs = check trello->/members/[memberId]/organizations;

Sample response:

[{"id": "60d5f2c8e4b0a12345678980", "name": "myteam", "displayName": "My Team"}]

Organizations

Get an Organization

Retrieves an organization (workspace) by its ID.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the organization.

Returns: Organization|error

Sample code:

trello:Organization org = check trello->/organizations/[orgId];

Sample response:

{"id": "60d5f2c8e4b0a12345678980", "name": "myteam", "displayName": "My Team", "desc": "Our development team workspace"}
Get Boards of Organization

Retrieves all boards belonging to an organization.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the organization.

Returns: Board[]|error

Sample code:

trello:Board[] boards = check trello->/organizations/[orgId]/boards;

Sample response:

[{"id": "60d5f2c8e4b0a12345678901", "name": "My Project Board", "closed": false, "idOrganization": "60d5f2c8e4b0a12345678980"}]
Get Members of Organization

Retrieves all members of an organization.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the organization.

Returns: Member[]|error

Sample code:

trello:Member[] members = check trello->/organizations/[orgId]/members;

Sample response:

[{"id": "60d5f2c8e4b0a12345678930", "fullName": "Jane Smith", "username": "janesmith"}]

Actions

Get a specific field on an Action

Retrieves a specific field on an action.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the action.
fieldActionFieldsYesThe field to retrieve.

Returns: Action|error

Sample code:

trello:Action action = check trello->/actions/[actionId]/data;

Sample response:

{"id": "60d5f2c8e4b0a12345678920", "type": "commentCard", "date": "2026-03-17T08:00:00.000Z"}
Update a Comment Action

Updates the text of a comment action.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the action.
queriesPutActionsIdTextQueriesYesQuery parameters including value (the new comment text).

Returns: error?

Sample code:

_ = check trello->/actions/[actionId]/text.put(queries = {value: "Updated comment text"});
Delete an Action

Deletes an action (only works for comment actions).

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the action.

Returns: error?

Sample code:

_ = check trello->/actions/[actionId].delete();
Get the Board for an Action

Retrieves the board associated with an action.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the action.

Returns: Board|error

Sample code:

trello:Board board = check trello->/actions/[actionId]/board;

Sample response:

{"id": "60d5f2c8e4b0a12345678901", "name": "My Project Board"}
Search Trello

Searches for boards, cards, members, and organizations matching a query.

Parameters:

NameTypeRequiredDescription
queriesGetSearchQueriesYesQuery parameters including query (required), modelTypes, idBoards, idOrganizations, and more.

Returns: InlineResponse2001|error

Sample code:

trello:InlineResponse2001 results = check trello->/search(queries = {query: "login feature"});

Sample response:

{"cards": [{"id": "60d5f2c8e4b0a12345678905", "name": "Implement login feature"}], "boards": [], "organizations": []}
Search Members

Searches for Trello members by name or username.

Parameters:

NameTypeRequiredDescription
queriesGetSearchMembersQueriesYesQuery parameters including query (required), limit, idBoard, idOrganization.

Returns: Member[]|error

Sample code:

trello:Member[] members = check trello->/search/members(queries = {query: "jane"});

Sample response:

[{"id": "60d5f2c8e4b0a12345678930", "fullName": "Jane Smith", "username": "janesmith"}]

Webhooks

Create Webhook

Creates a new webhook for receiving callbacks on model changes.

Parameters:

NameTypeRequiredDescription
payloadWebhooksBodyYesRequest body with callbackURL, idModel, description, and active fields.

Returns: Webhook|error

Sample code:

trello:Webhook webhook = check trello->/webhooks.post({
callbackURL: "https://myapp.example.com/trello/webhook",
idModel: boardId,
description: "Board change notifications"
});

Sample response:

{"id": "60d5f2c8e4b0a12345678990", "description": "Board change notifications", "idModel": "60d5f2c8e4b0a12345678901", "callbackURL": "https://myapp.example.com/trello/webhook", "active": true}
Get a Webhook

Retrieves a webhook by its ID.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the webhook.

Returns: Webhook|error

Sample code:

trello:Webhook webhook = check trello->/webhooks/[webhookId];

Sample response:

{"id": "60d5f2c8e4b0a12345678990", "description": "Board change notifications", "idModel": "60d5f2c8e4b0a12345678901", "callbackURL": "https://myapp.example.com/trello/webhook", "active": true}
Update Webhook

Updates a webhook's callback URL, model, or active status.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the webhook.
payloadWebhooksIdBodyYesRequest body with fields to update.

Returns: Webhook|error

Sample code:

trello:Webhook updated = check trello->/webhooks/[webhookId].put({
description: "Updated webhook",
active: false
});

Sample response:

{"id": "60d5f2c8e4b0a12345678990", "description": "Updated webhook", "active": false}
Delete Webhook

Deletes a webhook.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the webhook.

Returns: error?

Sample code:

_ = check trello->/webhooks/[webhookId].delete();

Custom fields

Create a new Custom Field on a Board

Creates a new custom field definition on a board.

Parameters:

NameTypeRequiredDescription
payloadCustomFieldsBodyYesRequest body with custom field configuration.

Returns: CustomField|error

Sample code:

trello:CustomField field = check trello->/customFields.post({
idModel: boardId,
modelType: "board",
name: "Priority",
'type: "list",
pos: "bottom"
});

Sample response:

{"id": "60d5f2c8e4b0a12345678910", "idModel": "60d5f2c8e4b0a12345678901", "name": "Priority", "type": "list", "pos": 1}
Get a Custom Field

Retrieves a custom field definition by its ID.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the custom field.

Returns: CustomField|error

Sample code:

trello:CustomField field = check trello->/customFields/[customFieldId];

Sample response:

{"id": "60d5f2c8e4b0a12345678910", "idModel": "60d5f2c8e4b0a12345678901", "name": "Priority", "type": "list"}
Delete a Custom Field definition

Deletes a custom field definition and removes it from all cards.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the custom field.

Returns: error?

Sample code:

_ = check trello->/customFields/[customFieldId].delete();

Notifications

Get a Notification

Retrieves a notification by its ID.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the notification.

Returns: Notification|error

Sample code:

trello:Notification notif = check trello->/notifications/[notificationId];

Sample response:

{"id": "60d5f2c8e4b0a12345678995", "type": "addedToCard", "unread": true, "date": "2026-03-17T09:00:00.000Z"}
Update Notification

Updates a notification's read status.

Parameters:

NameTypeRequiredDescription
idTrelloIDYesThe ID of the notification.
queriesPutNotificationsIdQueriesNoQuery parameters including unread.

Returns: Notification|error

Sample code:

trello:Notification notif = check trello->/notifications/[notificationId].put(queries = {unread: false});

Sample response:

{"id": "60d5f2c8e4b0a12345678995", "type": "addedToCard", "unread": false}

Tokens

Get a Token

Retrieves information about an API token.

Parameters:

NameTypeRequiredDescription
tokenValuestringYesThe token value.

Returns: Token|error

Sample code:

trello:Token tokenInfo = check trello->/tokens/[apiToken];

Sample response:

{"id": "60d5f2c8e4b0a12345678998", "identifier": "Ballerina Connector", "idMember": "60d5f2c8e4b0a12345678930", "dateExpires": null}
Delete a Token

Revokes and deletes a token.

Parameters:

NameTypeRequiredDescription
tokenValuestringYesThe token value.

Returns: error?

Sample code:

_ = check trello->/tokens/[apiToken].delete();