---
openapi: 3.0.3
info:
  title: Braze REST API – Update scheduled API-triggered Canvases
  description: |
    ## Prerequisites

    To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key-permissions) with the `canvas.trigger.schedule.update` 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/trigger/schedule/update":
    post:
      summary: Update scheduled API-triggered Canvases
      operationId: post_canvas_trigger_schedule_update_post_update_scheduled_triggered_canvases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScheduledTriggeredCanvasesRequest'
            examples:
              local_time:
                summary: Move a schedule to a local send time
                value:
                  canvas_id: canvas_identifier
                  schedule_id: schedule_identifier
                  schedule:
                    time: '2030-05-24T21:30:00'
                    in_local_time: true
      responses:
        "201":
          description: |
            The request was accepted and the scheduled Canvas was updated. No action needed.

            If the Canvas is archived or paused, the response also includes a `notice` field. If the Canvas is archived, you see this `notice` message: "The Canvas is archived. Unarchive the Canvas to ensure trigger requests will take effect." If the Canvas is paused, you see this `notice` message: "The Canvas is paused. Resume the Canvas to ensure trigger requests will take effect."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateScheduledTriggeredCanvasesResponse'
              examples:
                success:
                  summary: Schedule updated
                  value:
                    message: success
                paused:
                  summary: Schedule updated for a paused Canvas
                  value:
                    notice: The Canvas is paused. Resume the Canvas to ensure trigger requests will take effect.
                    message: success
        "400":
          description: |
            Bad request. To resolve it:

            - **The `canvas_id` is missing or isn't a string:** Pass a valid `canvas_id` string. Find it with the [Export Canvas list endpoint]({{site.baseurl}}/api/endpoints/export/canvas/get_canvases/).
            - **The `schedule_id` is missing or isn't a string:** Pass the `schedule_id` returned when you created the schedule.
            - **The request doesn't include a `schedule` object to update:** Include a `schedule` object in the request.
            - **The `time` is missing, malformed, or in the past:** Pass `schedule.time` as a future ISO 8601 UTC datetime.
            - **For local or optimal delivery, the `time` is in the past:** Pass a future `schedule.time` for local or optimal delivery.
            - **Both `in_local_time` and `at_optimal_time` are `true`:** Set only one of `in_local_time` or `at_optimal_time`.
            - **`segment_id` isn't supported on this endpoint:** Remove `segment_id` from the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_canvas_id:
                  summary: The canvas_id is missing or isn't a string
                  value:
                    message: canvas_id must be a string of the Canvas api identifier
                invalid_schedule_id:
                  summary: The schedule_id is missing or isn't a string
                  value:
                    message: "'schedule_id' must be a valid identifier of a schedule object"
                missing_schedule:
                  summary: The request doesn't include a schedule object
                  value:
                    message: "Schedule updates must update the 'schedule'"
                invalid_time:
                  summary: The time is missing, malformed, or in the past
                  value:
                    message: "'time' must be an ISO 8601 time in UTC that has not passed"
                local_time_in_past:
                  summary: The local or optimal time is in the past
                  value:
                    message: "'time' must be an ISO 8601 time in UTC that is not in the past"
                local_and_optimal:
                  summary: Both in_local_time and at_optimal_time are true
                  value:
                    message: "only one of 'in_local_time' and 'at_optimal_time' can be true"
                segment_id_not_supported:
                  summary: segment_id isn't supported
                  value:
                    message: "'segment_id' is not supported on this endpoint"
        "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.trigger.schedule.update` 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.trigger.schedule.update` permission.
        Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`.
  schemas:
    Schedule:
      title: Schedule object
      type: object
      required: [time]
      description: |
        See [schedule object]({{site.baseurl}}/api/objects_filters/schedule_object/). For the fields, see the [create schedule documentation]({{site.baseurl}}/api/endpoints/messaging/schedule_messages/post_schedule_triggered_canvases/).
      properties:
        time:
          type: string
          description: Time to send the message, as an ISO 8601 datetime string.
          example: '2030-05-24T21:30:00'
        in_local_time:
          type: boolean
          example: true
        at_optimal_time:
          type: boolean
          example: false
    UpdateScheduledTriggeredCanvasesRequest:
      title: Update scheduled API-triggered Canvas request
      type: object
      required: [canvas_id, schedule_id, schedule]
      properties:
        canvas_id:
          type: string
          description: See [Canvas identifier]({{site.baseurl}}/api/identifier_types/).
          example: canvas_identifier
        schedule_id:
          type: string
          description: The `schedule_id` to update (obtained from the response to create schedule).
          example: schedule_identifier
        schedule:
          $ref: '#/components/schemas/Schedule'
    UpdateScheduledTriggeredCanvasesResponse:
      title: Update scheduled API-triggered Canvas response
      type: object
      properties:
        notice:
          type: string
          description: Included when the Canvas is archived or paused.
          example: The Canvas is paused. Resume the Canvas to ensure trigger requests will take effect.
        message:
          type: string
          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.