---
openapi: 3.0.3
info:
  title: Braze REST API – Export Canvas list
  description: |
    ## Prerequisites

    To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key-permissions) with the `canvas.list` permission.

    ## Rate limit

    We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/).
  version: 1.0.0
  contact:
    name: Braze Support
    url: https://www.braze.com/docs/braze_support/
  license:
    name: Braze Documentation
    url: https://www.braze.com/docs/api/home/
servers:
  - url: https://rest.iad-01.braze.com
    description: US-01
  - url: https://rest.iad-02.braze.com
    description: US-02
  - url: https://rest.iad-03.braze.com
    description: US-03
  - url: https://rest.iad-04.braze.com
    description: US-04
  - url: https://rest.iad-05.braze.com
    description: US-05
  - url: https://rest.iad-06.braze.com
    description: US-06
  - url: https://rest.iad-07.braze.com
    description: US-07
  - url: https://rest.iad-08.braze.com
    description: US-08
  - url: https://rest.us-10.braze.com
    description: US-10
  - url: https://rest.fra-01.braze.eu
    description: EU-01
  - url: https://rest.fra-02.braze.eu
    description: EU-02
  - url: https://rest.au-01.braze.com
    description: AU-01
  - url: https://rest.id-01.braze.com
    description: ID-01
  - url: https://rest.jp-01.braze.com
    description: JP-01
  - url: https://rest.kr-01.braze.com
    description: KR-01
security:
- BearerAuth: []
paths:
  "/canvas/list":
    get:
      summary: Export Canvas list
      operationId: get_canvas_list_get_canvases
      parameters:
        - name: page
          in: query
          required: false
          description: The page of Canvases to return, defaults to `0` (returns the first set of up to 100)
          schema:
            type: integer
            minimum: 0
            default: 0
          example: 1
        - name: include_archived
          in: query
          required: false
          description: Whether or not to include archived Canvases, defaults to `false`.
          schema:
            type: boolean
            default: false
          example: false
        - name: sort_direction
          in: query
          required: false
          description: |
            - Sort creation time from newest to oldest: pass in the value `desc`.
            - Sort creation time from oldest to newest: pass in the value `asc`.

            If `sort_direction` is not included, the default order is oldest to newest.
          schema:
            type: string
            enum:
              - desc
              - asc
          example: desc
        - name: last_edit.time[gt]
          in: query
          required: false
          description: Filters the results and only returns Canvases that were edited greater than the time provided until now. Format is `yyyy-MM-DDTHH:mm:ss`.
          schema:
            type: string
          example: "2020-06-28T23:59:59-05:00"
      responses:
        "200":
          description: The request succeeded and the response body includes the Canvas list. No action needed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CanvasesResponse'
              examples:
                success:
                  summary: Canvas list
                  value:
                    canvases:
                      - id: canvas_api_identifier
                        last_edited: "2020-06-28T23:59:59+00:00"
                        name: Example Canvas
                        tags:
                          - example_tag
                        status: active
                    message: success
        "400":
          description: Bad request. The `page` value isn't an integer. Pass a non-negative integer for `page`, then retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                page_not_integer:
                  summary: page isn't an integer
                  value:
                    message: page must be an integer
        "401":
          description: |
            Unauthorized. The REST API key is missing, malformed, or sent to the wrong REST endpoint. Send the key as `Authorization: Bearer YOUR_REST_API_KEY` to the correct [REST endpoint]({{site.baseurl}}/api/basics/#endpoints). For more causes, see [Errors and responses]({{site.baseurl}}/api/errors/#fatal-errors).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_api_key:
                  summary: Invalid API key
                  value:
                    message: 'Invalid API key: YOUR_REST_API_KEY'
        "403":
          description: Access denied. The REST API key doesn't have the required permission. Use a REST API key that has the `canvas.list` permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                access_denied:
                  summary: Missing permission
                  value:
                    message: Access Denied
        "429":
          description: |
            Rate limited. You exceeded the rate limit for this endpoint. Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                over_rate_limit:
                  summary: Over rate limit
                  value:
                    message: You have exceeded your limit of 250000 requests per hour. Please contact your account executive to increase your limit. If you do not have their info, you may contact Braze directly at https://www.braze.com/contact/.
        5XX:
          description: |
            Internal server error. An unexpected error occurred on the Braze server. Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: REST API key
      description: |
        REST API keys are created in the Braze dashboard at **Settings → APIs and
        Identifiers → API Keys**. The key must include the `canvas.list` permission.
        Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`.
  schemas:
    CanvasesResponse:
      title: Export Canvas list response
      type: object
      properties:
        canvases:
          type: array
          items:
            title: Canvas
            type: object
            properties:
              id:
                type: string
                description: The Canvas API identifier.
              last_edited:
                type: string
                description: The last edited time for the message, as an ISO 8601 string.
              name:
                type: string
                description: The Canvas name.
              tags:
                type: array
                items:
                  type: string
                description: The tag names associated with the Canvas formatted as strings.
              status:
                type: string
                description: The status of the Canvas. One of `active`, `stopped`, `draft`, or `archived`.
                enum:
                  - active
                  - stopped
                  - draft
                  - archived
        message:
          type: string
          description: Returns 'success' when the request completes without errors.
          example: success
    ErrorResponse:
      title: Error
      type: object
      properties:
        message:
          type: string
          description: The error message describing why the request failed.
        errors:
          type: array
          description: Non-fatal errors encountered while processing the request. Data unaffected by these errors is still processed.
          items:
            type: object
            properties:
              type:
                type: string
                description: The error type.
