> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getaptly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List cards

> Returns a paginated list of cards on the board.

Field values are keyed by field UUID — use the schema endpoint to map keys to labels.
Money fields are returned as `{ amount, currency }` where `amount` is a decimal.

All filter params are optional and ANDed together.




## OpenAPI

````yaml /openapi.yaml get /api/board/{boardId}
openapi: 3.0.3
info:
  title: Aptly API
  version: '1.0'
  description: >
    The Aptly API lets you read and write cards on any Aptly board from external
    systems.


    All requests require an API key passed as the `x-token` header.

    API keys are scoped to your company and work across all boards.
servers:
  - url: https://core-api.getaptly.com
    description: Production
security:
  - ApiKeyHeader: []
paths:
  /api/board/{boardId}:
    get:
      tags:
        - Cards
      summary: List cards
      description: >
        Returns a paginated list of cards on the board.


        Field values are keyed by field UUID — use the schema endpoint to map
        keys to labels.

        Money fields are returned as `{ amount, currency }` where `amount` is a
        decimal.


        All filter params are optional and ANDed together.
      operationId: listCards
      parameters:
        - name: boardId
          in: path
          required: true
          schema:
            type: string
          description: The board's UUID.
        - name: page
          in: query
          required: true
          schema:
            type: integer
            minimum: 0
            maximum: 9999
          description: Zero-based page number.
        - name: pageSize
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 20
          description: Number of cards per page.
        - name: updatedAtMin
          in: query
          schema:
            type: string
            format: date-time
          description: Only return cards updated after this ISO timestamp.
        - name: includeArchived
          in: query
          schema:
            type: boolean
            default: false
          description: Include archived cards.
        - name: relatedId
          in: query
          schema:
            type: string
          description: Only return cards where `references.value` contains this ID.
        - name: contactEmail
          in: query
          schema:
            type: string
          description: >-
            Resolves the email to contact IDs, then filters cards referencing
            those contacts.
        - name: keyTerm
          in: query
          schema:
            type: string
          description: >-
            Full-text autocomplete search on card title using the Atlas Search
            index.
        - name: assignee
          in: query
          schema:
            type: string
          description: Filter cards by assignee user ID.
      responses:
        '200':
          description: Paginated list of cards.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Card'
                  count:
                    type: integer
                    description: Total number of matching cards.
                  page:
                    type: integer
                  pageSize:
                    type: integer
        '401':
          description: Invalid or missing API key.
        '403':
          description: API access is disabled for this board.
        '404':
          description: Board not found.
      security:
        - ApiKeyHeader: []
        - DelegateToken: []
components:
  schemas:
    Card:
      type: object
      properties:
        cardId:
          type: string
          description: Unique ID of the card.
        boardUuid:
          type: string
          description: UUID of the board this card belongs to.
        archived:
          type: boolean
        assignee:
          type: string
          description: Full name of the assigned user.
        lastActivity:
          type: object
          nullable: true
          description: >-
            Most recent conversation activity on the card (email, SMS or call),
            or null if the card has none.
          properties:
            content:
              type: string
              nullable: true
              description: Body/text preview of the most recent message.
            type:
              type: string
              nullable: true
              description: Activity type, e.g. `email`, `sms`, `voice`.
            direction:
              type: string
              nullable: true
              enum:
                - in
                - out
              description: Direction of the message — `in` (inbound) or `out` (outbound).
            publishedAt:
              type: string
              format: date-time
              nullable: true
            conversationUrl:
              type: string
              nullable: true
              description: >-
                Deep link to the conversation thread in Aptly. Null when the
                activity is not attached to a thread.
      additionalProperties:
        description: >-
          Additional properties are dynamic board fields keyed by their field
          UUID.
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-token
    DelegateToken:
      type: apiKey
      in: header
      name: Authorization
      description: 'Delegate token issued by the platform. Format: `DelegateToken <token>`'

````