--- openapi: 3.0.3 info: title: Braze REST API – Schedule 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.create` permission. ## Rate limit When you use connected audience filters in your request, this endpoint has a rate limit of 250 requests per minute. Otherwise, if you specify an `external_id`, this endpoint has a default rate limit of 250,000 requests per hour, shared between the endpoints documented in [API rate limits]({{site.baseurl}}/api/api_limits#requests-with-shared-rate-limits). This endpoint supports [batching API requests]({{site.baseurl}}/api/api_limits#batching-api-requests). One request can include any of the following: - Up to 50 `recipients` by default - A [connected audience]({{site.baseurl}}/api/objects_filters/connected_audience) of any size **Note:** Canvas entries are recorded at the scheduled message time, not when this API request is made. Users triggered for a future-dated schedule won't appear as entries until that scheduled time arrives. 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/create": post: summary: Schedule API-triggered Canvases operationId: post_canvas_trigger_schedule_create_post_schedule_triggered_canvases requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ScheduleTriggeredCanvasesRequest' examples: recipients_and_audience: summary: Schedule for an external user ID within a connected audience value: canvas_id: canvas_identifier recipients: - external_user_id: external_user_identifier context: {} audience: AND: - custom_attribute: custom_attribute_name: eye_color comparison: equals value: blue - custom_attribute: custom_attribute_name: favorite_foods comparison: includes_value value: pizza - OR: - custom_attribute: custom_attribute_name: last_purchase_time comparison: less_than_x_days_ago value: 2 - push_subscription_status: comparison: is value: opted_in - email_subscription_status: comparison: is_not value: subscribed - last_used_app: comparison: after value: '2019-07-22T13:17:55+0000' broadcast: false context: {} schedule: time: '2030-01-01T09:00:00Z' in_local_time: false at_optimal_time: false user_alias: summary: Schedule for a user alias value: canvas_id: canvas_identifier recipients: - user_alias: alias_name: example_alias alias_label: example_label schedule: time: '2030-01-01T09:00:00Z' responses: "201": description: The request was accepted. The response includes a `dispatch_id` and `schedule_id`. No action needed. content: application/json: schema: $ref: '#/components/schemas/ScheduleTriggeredCanvasesResponse' examples: success: summary: Canvas scheduled value: dispatch_id: dispatch_identifier schedule_id: schedule_identifier 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 Canvas can't be triggered by the API:** Set the Canvas entry to **API-triggered** delivery, then retry. - **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`. - **The `recipients` value isn't an array of objects that each include a user identifier:** Pass `recipients` as an array of objects, each with an `external_user_id`, `user_alias`, or `braze_id`. - **The `recipients` array is empty:** Include at least one recipient, or use `broadcast`. - **The `recipients` array exceeds the maximum allowed length:** Send fewer recipients per request (up to the API-triggered recipient limit). - **The `broadcast` value isn't a boolean:** Pass `broadcast` as `true` or `false`. - **`broadcast` is `true` but `recipients` or `external_user_ids` were also provided:** Set `broadcast` to `true` only when sending to a segment or connected audience, without explicit recipients. - **No recipients were provided and `broadcast` isn't `true`:** Include `recipients`, or set `broadcast` to `true`. - **The `context` value isn't an object:** Pass `context` as an object. - **The `context` payload is too large:** Reduce the size of `context` below your workspace's API trigger properties limit. - **`segment_id` isn't supported on this endpoint:** Remove `segment_id` from the request. **Note:** If your workspace accepts `canvas_entry_properties` instead of `context`, error messages name `canvas_entry_properties` in place of `context`. 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 canvas_not_api_triggered: summary: The Canvas can't be triggered by the API value: message: Canvas must be triggerable by API 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" malformed_recipients: summary: The recipients value is malformed value: message: "'recipients' must be an array of objects, each containing a user identifier and optional 'context'" empty_recipients: summary: The recipients array is empty value: message: when including recipients, there must be at least one recipient specified too_many_recipients: summary: Too many recipients value: message: Max input length exceeded. broadcast_not_boolean: summary: The broadcast value isn't a boolean value: message: Broadcast must be a boolean broadcast_with_recipients: summary: Broadcast with explicit recipients value: message: Cannot send messages to recipients with the broadcast parameter set to true. Broadcast is only available when sending to a Segment or Connected Audience missing_recipients: summary: No recipients and broadcast isn't true value: message: Must provide recipients unless the broadcast parameter is true context_not_object: summary: The context value isn't an object value: message: "'context' must be an object" context_too_large: summary: The context payload is too large value: message: "'context' is too large" 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.create` 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' 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.create` permission. Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`. schemas: UserAlias: title: User alias type: object required: [alias_name, alias_label] description: See [user alias object]({{site.baseurl}}/api/objects_filters/user_alias_object). properties: alias_name: type: string example: example_alias alias_label: type: string example: example_label CanvasRecipient: title: Recipient type: object properties: user_alias: allOf: - $ref: '#/components/schemas/UserAlias' description: User alias of user to receive message. external_user_id: type: string description: External identifier of user to receive message. example: external_user_identifier context: type: object additionalProperties: true description: Canvas context properties for this user. Schedule: title: Schedule object type: object required: [time] description: See [schedule object]({{site.baseurl}}/api/objects_filters/schedule_object/). properties: time: type: string description: Time to send the message, as an ISO 8601 datetime string. example: '2030-01-01T09:00:00Z' in_local_time: type: boolean example: false at_optimal_time: type: boolean example: false ScheduleTriggeredCanvasesRequest: title: Schedule API-triggered Canvas request type: object required: [canvas_id, schedule] properties: canvas_id: type: string description: See [Canvas identifier]({{site.baseurl}}/api/identifier_types/). example: canvas_identifier recipients: type: array items: $ref: '#/components/schemas/CanvasRecipient' description: | See [recipients object]({{site.baseurl}}/api/objects_filters/recipient_object/). Including `recipients` will send only to the provided user IDs if they are in the campaign's segment. audience: title: Connected audience object type: object additionalProperties: true description: | See [connected audience]({{site.baseurl}}/api/objects_filters/connected_audience/). Including `audience` will only send to users in the audience. broadcast: type: boolean default: false description: | You must set `broadcast` to true when sending a message to an entire segment that a campaign or Canvas targets. This parameter defaults to false (as of August 31, 2017). If `broadcast` is set to true, a `recipients` list cannot be included. However, use caution when setting `broadcast: true`, as unintentionally setting this flag may cause you to send your message to a larger than expected audience. If `recipients` and `audience` are not provided and `broadcast` is not set to `false`, the message will send to the entire segment targeted by the Canvas. example: false context: type: object additionalProperties: true description: | Personalization key-value pairs for all users in this send. See [Canvas context object]({{site.baseurl}}/user_guide/messaging/canvas/canvas_components/context/). Every workspace also accepts `canvas_entry_properties` for these key-value pairs, at both the request level and the recipient level. If you're not sure whether your workspace supports `context`, use `canvas_entry_properties`. These key-value pairs apply to the first step for all users in this send. For any keys that conflict between these trigger properties and those in a Recipients Object, the value from the Recipients Object will be used. schedule: $ref: '#/components/schemas/Schedule' ScheduleTriggeredCanvasesResponse: title: Schedule API-triggered Canvas response type: object properties: dispatch_id: type: string example: dispatch_identifier schedule_id: type: string description: Save this identifier to update or delete the scheduled Canvas later. example: schedule_identifier 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.