trello Lists API
Operations for creating, retrieving, updating, and archiving lists on boards.
OpenAPI Specification
openapi: 3.1.0
info:
title: Trello REST Actions Lists API
description: The Trello REST API provides programmatic access to Trello boards, lists, cards, members, labels, checklists, and other resources that make up the Trello project management platform. Developers can create, read, update, and delete Trello objects, manage team collaboration workflows, and automate task management processes. The API uses key and token based authentication and returns JSON responses for all endpoints.
version: '1'
contact:
name: Atlassian Developer Support
url: https://developer.atlassian.com/support
termsOfService: https://www.atlassian.com/legal/cloud-terms-of-service
servers:
- url: https://api.trello.com/1
description: Trello API v1 Production Server
security:
- apiKey: []
apiToken: []
tags:
- name: Lists
description: Operations for creating, retrieving, updating, and archiving lists on boards.
paths:
/lists:
post:
operationId: createList
summary: Create a List
description: Creates a new list on the specified board.
tags:
- Lists
parameters:
- name: name
in: query
required: true
description: The name for the new list.
schema:
type: string
minLength: 1
maxLength: 16384
- name: idBoard
in: query
required: true
description: The ID of the board the list should be created on.
schema:
type: string
- name: idListSource
in: query
description: The ID of a list to copy into the new list.
schema:
type: string
- name: pos
in: query
description: The position of the list on the board.
schema:
type: string
default: top
responses:
'200':
description: Successfully created the list.
content:
application/json:
schema:
$ref: '#/components/schemas/TrelloList'
'400':
description: Bad request.
'401':
description: Unauthorized.
/lists/{id}:
get:
operationId: getList
summary: Get a List
description: Retrieves a single list by its identifier.
tags:
- Lists
parameters:
- $ref: '#/components/parameters/idParam'
- name: fields
in: query
description: A comma-separated list of list fields to return.
schema:
type: string
default: name,closed,idBoard,pos
responses:
'200':
description: Successfully retrieved the list.
content:
application/json:
schema:
$ref: '#/components/schemas/TrelloList'
'401':
description: Unauthorized.
'404':
description: List not found.
put:
operationId: updateList
summary: Update a List
description: Updates a list's name, position, closed status, or board assignment.
tags:
- Lists
parameters:
- $ref: '#/components/parameters/idParam'
- name: name
in: query
description: The new name for the list.
schema:
type: string
minLength: 1
maxLength: 16384
- name: closed
in: query
description: Whether the list is closed (archived).
schema:
type: boolean
- name: idBoard
in: query
description: The ID of the board to move the list to.
schema:
type: string
- name: pos
in: query
description: The new position of the list.
schema:
type: string
- name: subscribed
in: query
description: Whether the authenticated member is subscribed to the list.
schema:
type: boolean
responses:
'200':
description: Successfully updated the list.
content:
application/json:
schema:
$ref: '#/components/schemas/TrelloList'
'401':
description: Unauthorized.
'404':
description: List not found.
/lists/{id}/actions:
get:
operationId: getListActions
summary: Get Actions on a List
description: Retrieves a list of actions associated with a list.
tags:
- Lists
parameters:
- $ref: '#/components/parameters/idParam'
- name: filter
in: query
description: A comma-separated list of action types to filter by.
schema:
type: string
responses:
'200':
description: Successfully retrieved list actions.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Action'
'401':
description: Unauthorized.
'404':
description: List not found.
/lists/{id}/board:
get:
operationId: getListBoard
summary: Get the Board for a List
description: Retrieves the board that a list belongs to.
tags:
- Lists
parameters:
- $ref: '#/components/parameters/idParam'
responses:
'200':
description: Successfully retrieved the board.
content:
application/json:
schema:
$ref: '#/components/schemas/Board'
'401':
description: Unauthorized.
'404':
description: List not found.
/lists/{id}/cards:
get:
operationId: getListCards
summary: Get Cards in a List
description: Retrieves all cards in a list.
tags:
- Lists
parameters:
- $ref: '#/components/parameters/idParam'
responses:
'200':
description: Successfully retrieved list cards.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Card'
'401':
description: Unauthorized.
'404':
description: List not found.
/lists/{id}/archiveAllCards:
post:
operationId: archiveAllListCards
summary: Archive All Cards in a List
description: Archives all cards in a list.
tags:
- Lists
parameters:
- $ref: '#/components/parameters/idParam'
responses:
'200':
description: Successfully archived all cards.
'401':
description: Unauthorized.
'404':
description: List not found.
/lists/{id}/moveAllCards:
post:
operationId: moveAllListCards
summary: Move All Cards in a List
description: Moves all cards in a list to a different list on the same or a different board.
tags:
- Lists
parameters:
- $ref: '#/components/parameters/idParam'
- name: idBoard
in: query
required: true
description: The ID of the destination board.
schema:
type: string
- name: idList
in: query
required: true
description: The ID of the destination list.
schema:
type: string
responses:
'200':
description: Successfully moved all cards.
'401':
description: Unauthorized.
'404':
description: List not found.
components:
schemas:
Membership:
type: object
description: Represents a membership record linking a member to a board or organization with a specific role.
properties:
id:
type: string
description: The unique identifier for the membership.
idMember:
type: string
description: The ID of the member.
memberType:
type: string
description: The type of membership.
enum:
- admin
- normal
- observer
unconfirmed:
type: boolean
description: Whether the membership is unconfirmed.
deactivated:
type: boolean
description: Whether the membership is deactivated.
Card:
type: object
description: Represents a Trello card, which is the fundamental unit of work on a board. Cards live within lists and can have members, labels, checklists, attachments, due dates, and comments.
properties:
id:
type: string
description: The unique identifier for the card.
name:
type: string
description: The name (title) of the card.
desc:
type: string
description: The description of the card in Markdown.
closed:
type: boolean
description: Whether the card is archived.
idBoard:
type: string
description: The ID of the board the card is on.
idList:
type: string
description: The ID of the list the card is in.
idShort:
type: integer
description: The short numeric identifier for the card within its board.
idMembers:
type: array
description: The IDs of members assigned to the card.
items:
type: string
idLabels:
type: array
description: The IDs of labels on the card.
items:
type: string
idChecklists:
type: array
description: The IDs of checklists on the card.
items:
type: string
idAttachmentCover:
type: string
description: The ID of the attachment used as the card cover.
pos:
type: number
description: The position of the card in its list.
due:
type: string
format: date-time
description: The due date for the card.
dueComplete:
type: boolean
description: Whether the due date has been marked as complete.
start:
type: string
format: date-time
description: The start date for the card.
url:
type: string
format: uri
description: The full URL of the card.
shortUrl:
type: string
format: uri
description: The short URL of the card.
shortLink:
type: string
description: The short link identifier for the card.
subscribed:
type: boolean
description: Whether the authenticated member is subscribed to the card.
dateLastActivity:
type: string
format: date-time
description: The date and time of the last activity on the card.
cover:
type: object
description: The card's cover image settings.
properties:
idAttachment:
type: string
color:
type: string
idUploadedBackground:
type: string
size:
type: string
enum:
- normal
- full
brightness:
type: string
idPlugin:
type: string
labels:
type: array
description: The labels on the card.
items:
$ref: '#/components/schemas/Label'
badges:
type: object
description: Badge counts and indicators for the card.
properties:
votes:
type: integer
attachments:
type: integer
comments:
type: integer
checkItems:
type: integer
checkItemsChecked:
type: integer
description:
type: boolean
due:
type: string
format: date-time
dueComplete:
type: boolean
subscribed:
type: boolean
Member:
type: object
description: Represents a Trello user who can be a member of boards, organizations, and cards.
properties:
id:
type: string
description: The unique identifier for the member.
username:
type: string
description: The username of the member.
fullName:
type: string
description: The full name of the member.
initials:
type: string
description: The initials of the member.
bio:
type: string
description: The biography of the member.
avatarHash:
type: string
description: The hash of the member's avatar image.
avatarUrl:
type: string
format: uri
description: The URL of the member's avatar image.
url:
type: string
format: uri
description: The URL of the member's Trello profile.
confirmed:
type: boolean
description: Whether the member's email has been confirmed.
memberType:
type: string
description: The type of member account.
status:
type: string
description: The activity status of the member.
idOrganizations:
type: array
description: The IDs of organizations the member belongs to.
items:
type: string
idBoards:
type: array
description: The IDs of boards the member has access to.
items:
type: string
TrelloList:
type: object
description: Represents a list on a Trello board. Lists are vertical columns that contain cards and represent stages in a workflow.
properties:
id:
type: string
description: The unique identifier for the list.
name:
type: string
description: The name of the list.
closed:
type: boolean
description: Whether the list is closed (archived).
idBoard:
type: string
description: The ID of the board the list belongs to.
pos:
type: number
description: The position of the list on the board.
subscribed:
type: boolean
description: Whether the authenticated member is subscribed to the list.
softLimit:
type: string
description: A soft limit for the number of cards in the list.
Board:
type: object
description: Represents a Trello board, which is the primary organizational unit containing lists and cards.
properties:
id:
type: string
description: The unique identifier for the board.
name:
type: string
description: The name of the board.
desc:
type: string
description: The description of the board.
descData:
type: object
description: Additional description data.
closed:
type: boolean
description: Whether the board is closed (archived).
idMemberCreator:
type: string
description: The ID of the member who created the board.
idOrganization:
type: string
description: The ID of the organization the board belongs to.
pinned:
type: boolean
description: Whether the board is pinned.
url:
type: string
format: uri
description: The full URL of the board.
shortUrl:
type: string
format: uri
description: The short URL of the board.
shortLink:
type: string
description: The short link identifier for the board.
prefs:
type: object
description: Board preferences and settings.
properties:
permissionLevel:
type: string
enum:
- org
- private
- public
hideVotes:
type: boolean
voting:
type: string
comments:
type: string
selfJoin:
type: boolean
cardCovers:
type: boolean
cardAging:
type: string
enum:
- pirate
- regular
background:
type: string
backgroundColor:
type: string
backgroundImage:
type: string
backgroundTile:
type: boolean
backgroundBrightness:
type: string
labelNames:
type: object
description: The names assigned to each label color on the board.
properties:
green:
type: string
yellow:
type: string
orange:
type: string
red:
type: string
purple:
type: string
blue:
type: string
sky:
type: string
lime:
type: string
pink:
type: string
black:
type: string
starred:
type: boolean
description: Whether the authenticated member has starred the board.
memberships:
type: array
description: The board's membership records.
items:
$ref: '#/components/schemas/Membership'
dateLastActivity:
type: string
format: date-time
description: The date and time of the last activity on the board.
dateLastView:
type: string
format: date-time
description: The date and time the authenticated member last viewed the board.
Action:
type: object
description: Represents an activity event that occurred on a Trello object, such as creating a card, adding a comment, or moving a card between lists.
properties:
id:
type: string
description: The unique identifier for the action.
idMemberCreator:
type: string
description: The ID of the member who performed the action.
type:
type: string
description: The type of action that was performed.
date:
type: string
format: date-time
description: The date and time the action was performed.
data:
type: object
description: Context data about the action, including references to the objects involved.
properties:
text:
type: string
description: The text content of the action, if applicable.
board:
type: object
description: Reference to the board involved in the action.
properties:
id:
type: string
name:
type: string
shortLink:
type: string
card:
type: object
description: Reference to the card involved in the action.
properties:
id:
type: string
name:
type: string
idShort:
type: integer
shortLink:
type: string
list:
type: object
description: Reference to the list involved in the action.
properties:
id:
type: string
name:
type: string
old:
type: object
description: The previous values of fields that were changed.
display:
type: object
description: Display information for rendering the action.
memberCreator:
$ref: '#/components/schemas/Member'
Label:
type: object
description: Represents a color-coded label that can be applied to cards for categorization and filtering.
properties:
id:
type: string
description: The unique identifier for the label.
idBoard:
type: string
description: The ID of the board the label belongs to.
name:
type: string
description: The name of the label.
color:
type: string
description: The color of the label.
enum:
- yellow
- purple
- blue
- red
- green
- orange
- black
- sky
- pink
- lime
- null
parameters:
idParam:
name: id
in: path
required: true
description: The ID of the resource.
schema:
type: string
securitySchemes:
apiKey:
type: apiKey
in: query
name: key
description: Your Trello API key, obtained from the Power-Ups admin page at https://trello.com/power-ups/admin.
apiToken:
type: apiKey
in: query
name: token
description: A user token that grants access to Trello resources. Obtained by authorizing via the /1/authorize route or OAuth 1.0.
externalDocs:
description: Trello REST API Documentation
url: https://developer.atlassian.com/cloud/trello/rest/