trello Cards API

openapi: 3.1.0
info:
  title: Trello REST Actions Cards 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: Cards
  description: Operations for creating, retrieving, updating, and deleting cards, including managing card attachments, checklists, comments, labels, members, and stickers.
paths:
  /cards:
    post:
      operationId: createCard
      summary: Create a Card
      description: Creates a new card on the specified list.
      tags:
      - Cards
      parameters:
      - name: name
        in: query
        description: The name for the card.
        schema:
          type: string
          minLength: 0
          maxLength: 16384
      - name: desc
        in: query
        description: The description for the card.
        schema:
          type: string
          maxLength: 16384
      - name: pos
        in: query
        description: The position of the card in the list.
        schema:
          type: string
          default: bottom
      - name: due
        in: query
        description: The due date for the card.
        schema:
          type: string
          format: date-time
      - name: start
        in: query
        description: The start date for the card.
        schema:
          type: string
          format: date-time
      - name: dueComplete
        in: query
        description: Whether the due date is complete.
        schema:
          type: boolean
          default: false
      - name: idList
        in: query
        required: true
        description: The ID of the list the card should be created in.
        schema:
          type: string
      - name: idMembers
        in: query
        description: Comma-separated list of member IDs to add to the card.
        schema:
          type: string
      - name: idLabels
        in: query
        description: Comma-separated list of label IDs to add to the card.
        schema:
          type: string
      - name: urlSource
        in: query
        description: A URL to attach to the card.
        schema:
          type: string
          format: uri
      - name: idCardSource
        in: query
        description: The ID of a card to copy into the new card.
        schema:
          type: string
      responses:
        '200':
          description: Successfully created the card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '400':
          description: Bad request. Missing required parameters.
        '401':
          description: Unauthorized.
  /cards/{id}:
    get:
      operationId: getCard
      summary: Get a Card
      description: Retrieves a single card by its identifier.
      tags:
      - Cards
      parameters:
      - $ref: '#/components/parameters/idParam'
      - name: fields
        in: query
        description: A comma-separated list of card fields to return.
        schema:
          type: string
          default: all
      - name: actions
        in: query
        description: A comma-separated list of action types to include.
        schema:
          type: string
      - name: attachments
        in: query
        description: Whether to include attachments.
        schema:
          type: string
          default: 'false'
      - name: members
        in: query
        description: Whether to include members.
        schema:
          type: boolean
          default: false
      - name: checkItemStates
        in: query
        description: Whether to include check item states.
        schema:
          type: boolean
          default: false
      - name: checklists
        in: query
        description: Whether to include checklists.
        schema:
          type: string
          enum:
          - all
          - none
          default: none
      responses:
        '200':
          description: Successfully retrieved the card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '401':
          description: Unauthorized.
        '404':
          description: Card not found.
    put:
      operationId: updateCard
      summary: Update a Card
      description: Updates the fields of a card, including name, description, position, due date, list assignment, and more.
      tags:
      - Cards
      parameters:
      - $ref: '#/components/parameters/idParam'
      - name: name
        in: query
        description: The new name for the card.
        schema:
          type: string
          maxLength: 16384
      - name: desc
        in: query
        description: The new description for the card.
        schema:
          type: string
          maxLength: 16384
      - name: closed
        in: query
        description: Whether the card is archived.
        schema:
          type: boolean
      - name: idMembers
        in: query
        description: Comma-separated list of member IDs.
        schema:
          type: string
      - name: idLabels
        in: query
        description: Comma-separated list of label IDs.
        schema:
          type: string
      - name: idList
        in: query
        description: The ID of the list to move the card to.
        schema:
          type: string
      - name: idBoard
        in: query
        description: The ID of the board to move the card to.
        schema:
          type: string
      - name: pos
        in: query
        description: The new position of the card.
        schema:
          type: string
      - name: due
        in: query
        description: The new due date for the card.
        schema:
          type: string
          format: date-time
      - name: start
        in: query
        description: The start date for the card.
        schema:
          type: string
          format: date-time
      - name: dueComplete
        in: query
        description: Whether the due date is complete.
        schema:
          type: boolean
      - name: subscribed
        in: query
        description: Whether the authenticated member is subscribed to the card.
        schema:
          type: boolean
      - name: cover
        in: query
        description: JSON string for the card cover.
        schema:
          type: string
      responses:
        '200':
          description: Successfully updated the card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '401':
          description: Unauthorized.
        '404':
          description: Card not found.
    delete:
      operationId: deleteCard
      summary: Delete a Card
      description: Permanently deletes a card. This action cannot be undone.
      tags:
      - Cards
      parameters:
      - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: Successfully deleted the card.
        '401':
          description: Unauthorized.
        '404':
          description: Card not found.
  /cards/{id}/actions:
    get:
      operationId: getCardActions
      summary: Get Actions on a Card
      description: Retrieves a list of actions (activity events) on a card.
      tags:
      - Cards
      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 card actions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Action'
        '401':
          description: Unauthorized.
        '404':
          description: Card not found.
  /cards/{id}/actions/comments:
    post:
      operationId: createCardComment
      summary: Add a Comment to a Card
      description: Adds a new comment to a card.
      tags:
      - Cards
      parameters:
      - $ref: '#/components/parameters/idParam'
      - name: text
        in: query
        required: true
        description: The comment text.
        schema:
          type: string
          minLength: 1
          maxLength: 16384
      responses:
        '200':
          description: Successfully added the comment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Action'
        '401':
          description: Unauthorized.
        '404':
          description: Card not found.
  /cards/{id}/attachments:
    get:
      operationId: getCardAttachments
      summary: Get Attachments on a Card
      description: Retrieves all attachments on a card.
      tags:
      - Cards
      parameters:
      - $ref: '#/components/parameters/idParam'
      - name: fields
        in: query
        description: A comma-separated list of attachment fields to return.
        schema:
          type: string
          default: all
      responses:
        '200':
          description: Successfully retrieved card attachments.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Attachment'
        '401':
          description: Unauthorized.
        '404':
          description: Card not found.
    post:
      operationId: createCardAttachment
      summary: Create an Attachment on a Card
      description: Adds a new attachment to a card, either from a URL or a file upload.
      tags:
      - Cards
      parameters:
      - $ref: '#/components/parameters/idParam'
      - name: name
        in: query
        description: The name for the attachment.
        schema:
          type: string
      - name: mimeType
        in: query
        description: The MIME type of the attachment.
        schema:
          type: string
      - name: url
        in: query
        description: A URL to attach to the card.
        schema:
          type: string
          format: uri
      responses:
        '200':
          description: Successfully created the attachment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attachment'
        '401':
          description: Unauthorized.
        '404':
          description: Card not found.
  /cards/{id}/checklists:
    get:
      operationId: getCardChecklists
      summary: Get Checklists on a Card
      description: Retrieves all checklists on a card.
      tags:
      - Cards
      parameters:
      - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: Successfully retrieved card checklists.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Checklist'
        '401':
          description: Unauthorized.
        '404':
          description: Card not found.
    post:
      operationId: createCardChecklist
      summary: Create a Checklist on a Card
      description: Creates a new checklist on the specified card.
      tags:
      - Cards
      parameters:
      - $ref: '#/components/parameters/idParam'
      - name: name
        in: query
        description: The name for the checklist.
        schema:
          type: string
      - name: idChecklistSource
        in: query
        description: The ID of a checklist to copy into the new checklist.
        schema:
          type: string
      - name: pos
        in: query
        description: The position of the checklist on the card.
        schema:
          type: string
          default: bottom
      responses:
        '200':
          description: Successfully created the checklist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checklist'
        '401':
          description: Unauthorized.
        '404':
          description: Card not found.
  /cards/{id}/labels:
    post:
      operationId: addCardLabel
      summary: Add a Label to a Card
      description: Adds an existing label to a card.
      tags:
      - Cards
      parameters:
      - $ref: '#/components/parameters/idParam'
      - name: value
        in: query
        required: true
        description: The ID of the label to add.
        schema:
          type: string
      responses:
        '200':
          description: Successfully added the label.
        '401':
          description: Unauthorized.
        '404':
          description: Card or label not found.
  /cards/{id}/labels/{idLabel}:
    delete:
      operationId: removeCardLabel
      summary: Remove a Label from a Card
      description: Removes a label from a card.
      tags:
      - Cards
      parameters:
      - $ref: '#/components/parameters/idParam'
      - name: idLabel
        in: path
        required: true
        description: The ID of the label to remove.
        schema:
          type: string
      responses:
        '200':
          description: Successfully removed the label.
        '401':
          description: Unauthorized.
        '404':
          description: Card or label not found.
  /cards/{id}/members:
    post:
      operationId: addCardMember
      summary: Add a Member to a Card
      description: Adds a member to a card.
      tags:
      - Cards
      parameters:
      - $ref: '#/components/parameters/idParam'
      - name: value
        in: query
        required: true
        description: The ID of the member to add.
        schema:
          type: string
      responses:
        '200':
          description: Successfully added the member.
        '401':
          description: Unauthorized.
        '404':
          description: Card or member not found.
  /cards/{id}/members/{idMember}:
    delete:
      operationId: removeCardMember
      summary: Remove a Member from a Card
      description: Removes a member from a card.
      tags:
      - Cards
      parameters:
      - $ref: '#/components/parameters/idParam'
      - name: idMember
        in: path
        required: true
        description: The ID of the member to remove.
        schema:
          type: string
      responses:
        '200':
          description: Successfully removed the member.
        '401':
          description: Unauthorized.
        '404':
          description: Card or member not found.
  /cards/{id}/stickers:
    get:
      operationId: getCardStickers
      summary: Get Stickers on a Card
      description: Retrieves all stickers on a card.
      tags:
      - Cards
      parameters:
      - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: Successfully retrieved card stickers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Sticker'
        '401':
          description: Unauthorized.
        '404':
          description: Card not found.
    post:
      operationId: addCardSticker
      summary: Add a Sticker to a Card
      description: Adds a sticker to a card.
      tags:
      - Cards
      parameters:
      - $ref: '#/components/parameters/idParam'
      - name: image
        in: query
        required: true
        description: The sticker image identifier.
        schema:
          type: string
      - name: top
        in: query
        required: true
        description: The top position of the sticker as a percentage.
        schema:
          type: number
      - name: left
        in: query
        required: true
        description: The left position of the sticker as a percentage.
        schema:
          type: number
      - name: zIndex
        in: query
        required: true
        description: The z-index of the sticker.
        schema:
          type: integer
      - name: rotate
        in: query
        description: The rotation of the sticker in degrees.
        schema:
          type: number
          default: 0
      responses:
        '200':
          description: Successfully added the sticker.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sticker'
        '401':
          description: Unauthorized.
        '404':
          description: Card not found.
components:
  schemas:
    CheckItem:
      type: object
      description: Represents a single item in a checklist that can be checked or unchecked.
      properties:
        id:
          type: string
          description: The unique identifier for the check item.
        name:
          type: string
          description: The name of the check item.
        state:
          type: string
          description: The completion state of the check item.
          enum:
          - complete
          - incomplete
        idChecklist:
          type: string
          description: The ID of the checklist the check item belongs to.
        pos:
          type: number
          description: The position of the check item in the checklist.
        due:
          type: string
          format: date-time
          description: The due date for the check item.
        idMember:
          type: string
          description: The ID of the member assigned to the check item.
    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
    Sticker:
      type: object
      description: Represents a decorative sticker placed on a card.
      properties:
        id:
          type: string
          description: The unique identifier for the sticker.
        image:
          type: string
          description: The image identifier for the sticker.
        imageUrl:
          type: string
          format: uri
          description: The URL of the sticker image.
        top:
          type: number
          description: The top position as a percentage.
        left:
          type: number
          description: The left position as a percentage.
        zIndex:
          type: integer
          description: The z-index of the sticker.
        rotate:
          type: number
          description: The rotation in degrees.
    Attachment:
      type: object
      description: Represents a file or URL attachment on a card.
      properties:
        id:
          type: string
          description: The unique identifier for the attachment.
        name:
          type: string
          description: The name of the attachment.
        url:
          type: string
          format: uri
          description: The URL of the attachment.
        bytes:
          type: integer
          description: The size of the attachment in bytes.
        date:
          type: string
          format: date-time
          description: The date the attachment was added.
        edgeColor:
          type: string
          description: The edge color of the attachment preview.
        idMember:
          type: string
          description: The ID of the member who added the attachment.
        isUpload:
          type: boolean
          description: Whether the attachment was uploaded (vs. linked).
        mimeType:
          type: string
          description: The MIME type of the attachment.
        previews:
          type: array
          description: Preview image versions of the attachment.
          items:
            type: object
            properties:
              id:
                type: string
              url:
                type: string
                format: uri
              width:
                type: integer
              height:
                type: integer
              bytes:
                type: integer
    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
    Checklist:
      type: object
      description: Represents a checklist on a card, containing a list of check items that can be marked as complete or incomplete.
      properties:
        id:
          type: string
          description: The unique identifier for the checklist.
        name:
          type: string
          description: The name of the checklist.
        idBoard:
          type: string
          description: The ID of the board the checklist belongs to.
        idCard:
          type: string
          description: The ID of the card the checklist is on.
        pos:
          type: number
          description: The position of the checklist on the card.
        checkItems:
          type: array
          description: The check items in the checklist.
          items:
            $ref: '#/components/schemas/CheckItem'
  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/