--- openapi: 3.0.3 info: title: Braze REST API – Export Canvas details description: 'Use this endpoint to export metadata about a Canvas, such as the name, time created, current status, and more. ' 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/details": get: summary: Export Canvas details description: | ## Prerequisites To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key/) with the `canvas.details` permission. ## Rate limit For rate limit details, see [API rate limits]({{site.baseurl}}/api/api_limits/). ## Request parameters The following table lists the request parameters for this endpoint. | Parameter | Required | Data Type | Description | | --------- | -------- | --------- | ----------- | | `canvas_id` | Required | String | See [Canvas API Identifier]({{site.baseurl}}/api/identifier_types/) | | `post_launch_draft_version` | Optional | Boolean | For Canvases that have a post-launch draft, setting this to `true` shows any draft changes available. Defaults to `false`. | | `include_has_translatable_content` | Optional | Boolean | When set to `true`, the API response includes a `has_translatable_content` field for each message. Defaults to `false`. | ## Example request The following sample request shows an example of how to export Canvas details. ``` curl --location -g --request GET 'https://rest.iad-01.braze.com/canvas/details?canvas_id={{canvas_identifier}}' \ --header 'Authorization: Bearer YOUR_REST_API_KEY' ``` ## Responses **Note:** All Canvas steps have a `next_paths` field, which is an array of `{name, next_step_id}` data. For Message steps, the `next_step_ids` field will be present, but will not contain data for other Canvas steps. ```json { "created_at": (string) the date created as ISO 8601 date, "updated_at": (string) the date updated as ISO 8601 date, "name": (string) the Canvas name, "description": (string) the Canvas description, "archived": (boolean) whether this Canvas is archived, "draft": (boolean) whether this Canvas is a draft, "enabled": (boolean) whether this Canvas is active or not, "has_post_launch_draft": (boolean) whether this Canvas has a post-launch draft, "schedule_type": (string) the type of scheduling action, "first_entry": (string) the date of first entry as ISO 8601 date, "last_entry": (string) the date of last entry as ISO 8601 date, "channels": (array of strings) step channels used with Canvas, "variants": [ { "name": (string) the name of variant, "id": (string) the API identifier of the variant, "first_step_ids": (array of strings) the API identifiers for first steps in variant, "first_step_id": (string) the API identifier of first step in variant (deprecated in November 2017, only included if the variant has only one first step) }, ... (more variations) ], "tags": (array of strings) the tag names associated with the Canvas, "teams" : (array) the names of the Teams associated with the Canvas, "steps": [ { "name": (string) the name of step, "type": (string) the type of Canvas component, "id": (string) the API identifier of the step, "next_step_ids": (array of strings) IDs for next steps that are full steps or Message steps, "next_paths": { (array of objects) // for Decision Splits, this property should evaluate to "Yes" or "No" // for Audience Path and Action Paths, this property should evaluate to the group name // for Experiment Paths, this property should evaluate to the path name // for other steps, this property should evaluate to "null" "name": (string) name the name of step, "next_step_id": (string) IDs for next steps that are full steps or Message steps, } "channels": (array of strings) the channels used in step, "messages": { "message_variation_id": (string) { // <=This is the actual id "channel": (string) the channel type of the message (for example, "email"), "has_translatable_content": (boolean) whether the message has translatable content (only present if `include_has_translatable_content` is true); `true` if locales are configured and the message contains at least one translation tag; `false` if no locales are configured or no translation tags detected; `null` if detection could not be completed, // channel-specific fields for this message, see Campaign Details endpoint API Response for example message responses } } }, ... (more steps) ], "message": (string) returns 'success' when the request completes without errors } ``` ### Messages by channel The following is an example response that includes Canvas messages sent through different channels (email, push, SMS, and in-app messages): ```json { "message": "success", "created_at": "2023-01-01T12:00:00Z", "updated_at": "2023-01-10T12:00:00Z", "name": "Multi-Channel Engagement", "description": "Complete profile reminder via multiple channels", "archived": false, "draft": false, "enabled": true, "has_post_launch_draft": true, "schedule_type": "date", "first_entry": "2023-01-01T12:00:00Z", "last_entry": "2023-01-10T12:00:00Z", "channels": ["email", "push", "sms", "in_app_message"], "variants": [ { "name": "Variant 1", "id": "variant_1_id", "first_step_ids": ["step_1"] } ], "tags": ["engagement", "multi-channel"], "teams": ["Marketing Team"], "steps": [ { "name": "Welcome Email", "type": "email", "id": "step_1", "next_step_ids": ["step_2"], "next_paths": [ { "name": "Next Step", "next_step_id": "step_2" } ], "channels": ["email"], "messages": { "message_1": { "channel": "email", "subject": "Welcome to Kitchenerie!", "body": "Welcome to the Kitchenerie family, {{first_name}}!" } } }, { "name": "Follow-Up Push Notification", "type": "push", "id": "step_2", "next_step_ids": ["step_3"], "next_paths": [ { "name": "Next Step", "next_step_id": "step_3" } ], "channels": ["push"], "messages": { "message_2": { "channel": "push", "title": "Don't Forget to Complete Your Kitchenerie Profile", "body": "Complete your Kitchenerie profile for access to special offers and local events." } } }, { "name": "Reminder SMS", "type": "sms", "id": "step_3", "next_step_ids": ["step_4"], "next_paths": [ { "name": "Next Step", "next_step_id": "step_4" } ], "channels": ["sms"], "messages": { "message_3": { "channel": "sms", "body": "Hi {{first_name}}, remember to complete Kitchenerie your profile!" } } }, { "name": "In-App Message", "type": "in_app_message", "id": "step_4", "next_step_ids": [], "next_paths": [], "channels": ["in_app_message"], "messages": { "message_4": { "channel": "in_app_message", "header": "Complete Your Kitchenerie Profile", "body": "Complete your Kitchenerie profile to unlock access to savings and local events!" } } } ] } ``` ## Response status codes The following table lists the responses for this endpoint, the error message you may receive, and how to resolve it. | Status code | Meaning | Error message | How to resolve | | --- | --- | --- | --- | | `200 OK` | The request succeeded and the response body includes the Canvas details. | `success` | No action needed. | | `400 Bad Request` | The `canvas_id` is missing, isn't a string, or doesn't match a Canvas in this workspace. | `canvas_id must be a string of the Canvas api identifier` | Pass a valid `canvas_id`. Find it with the [Export Canvas list endpoint]({{site.baseurl}}/api/endpoints/export/canvas/get_canvases/). | | `401 Unauthorized` | The REST API key is missing, malformed, or sent to the wrong REST endpoint. | `Invalid API key` | 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). | | `403 Access Denied` | The REST API key doesn't have the required permission. | `Access Denied` | Use a REST API key that has the `canvas.details` permission. | | `429 Rate Limited` | You exceeded the rate limit for this endpoint. | `Over rate limit` | Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/). | | `5XX Internal Server Error` | An unexpected error occurred on the Braze server. | `Internal Server Error` | Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). | **Tip:** For help with CSV and API exports, visit [Export troubleshooting]({{site.baseurl}}/user_guide/data/distribution/export_braze_data/export_troubleshooting/). operationId: get_canvas_details_get_canvas_details tags: - Export responses: '200': description: Success parameters: - name: canvas_id in: query required: true description: See Canvas API Identifier schema: type: string - name: post_launch_draft_version in: query required: false description: For Canvases that have a post-launch draft, setting this to `true` shows any draft changes available. Defaults to `false`. schema: type: boolean - name: include_has_translatable_content in: query required: false description: When set to `true`, the API response includes a `has_translatable_content` field for each message. Defaults to `false`. schema: type: boolean components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: REST API key