openapi: 3.2.0 info: description: These APIs will help you manage different workflows in Blueshift. Our powerful REST APIs provide an easy way to integrate your data and third party applications with Blueshift. version: 1.0.0 title: Blueshift Shared assets API contact: email: support@getblueshift.com servers: - url: https://api.getblueshift.com - url: https://api.eu.getblueshift.com tags: - name: Shared assets description: Manage reusable assets such as HTML, rich text, subject lines, and visual editor content. paths: /api/v1/shared_assets.json: get: summary: List shared assets description: 'Retrieve a list of shared assets: HTML, rich text, subject lines, and visual editor content.' tags: - Shared assets security: - user_api_auth: [] parameters: - name: asset_type[] in: query description: 'Filter by one or more asset types. Repeat the parameter for multiple values. Allowed values: `html`, `rich_text`, `visual_editor`, `subject`.' schema: type: array items: type: string enum: - html - rich_text - visual_editor - subject style: form explode: true example: - html - visual_editor - name: display_name in: query description: Returns assets whose display name contains the specified substring. An empty string returns all. schema: type: string example: Banner - name: archived in: query description: Archived status filter. Use `0` for active/unarchived, `1` for archived, or omit to include both. In the response, this field is returned as a boolean (`true`/`false`). schema: type: integer enum: - 0 - 1 examples: active: summary: Active (unarchived) value: 0 archived: summary: Archived value: 1 all: summary: All (omit parameter) value: '' - name: page in: query description: 'Which page of results to fetch. **Zero-based index.** Example: `page=0&per_page=25` returns the first 25 results, `page=1&per_page=25` returns the next 25.' schema: type: integer example: '0' - name: per_page in: query description: The number of results to return per page. schema: type: integer example: 25 responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: id: type: integer description: Unique numeric ID of the asset. example: 24990 uuid: type: string description: Unique UUID of the asset. example: 2c7967ff-5404-481d-83d9-90a11d2fa8e7 asset_type: type: string enum: - html - rich_text - visual_editor - subject description: Type of shared asset. example: subject shareable_name: type: string description: System name used for sharing/reuse. example: footer_template display_name: type: string description: Human-readable display name. example: New subject & preheader archived: type: boolean description: Archived status of the asset. example: false author: type: string description: Author of the asset. example: Content Team email: type: string format: email description: Email address of the author. example: team@example.com templates: type: array description: Templates linked to this asset. items: type: object properties: name: type: string example: Welcome Email uuid: type: string example: 1111aaaa-2222-bbbb-3333-cccc4444dddd resource_type: type: string example: EmailTemplate archived: type: boolean example: false template_count: type: integer example: 0 asset_count: type: integer example: 0 updated_at: type: string format: date-time description: Last update (ISO 8601). example: '2025-06-04T07:23:02.000Z' content: type: string description: Asset content (HTML, rich text, or subject line). example: change me!!! locked_parents: type: array items: type: string lockable_children: type: array items: type: string example: - uuid: a1111111-b222-4ccc-8ddd-eeeeeeee0001 asset_type: html shareable_name: footer_template display_name: Footer Template archived: false author: Content Team email: team@example.com templates: - name: Welcome Email uuid: 1111aaaa-2222-bbbb-3333-cccc4444dddd resource_type: EmailTemplate archived: false template_count: 1 updated_at: '2025-08-22T18:12:47.000Z' content: "\n \n {% for product in recommendations.block1.products %}\n \n {% endfor %}\n \n
\n \n \n \n

{{ product.title }}

\n

{{ product.extended_attributes.description }}

\n Buy Now\n
" locked_parents: [] lockable_children: [] - uuid: b2222222-c333-4ddd-8eee-ffffffff0002 asset_type: subject shareable_name: subject_line_offer display_name: Subject Line – Summer Offer archived: false author: Copywriter email: copywriter@example.com templates: [] template_count: 0 updated_at: '2025-08-23T11:20:00.000Z' content: Get 20% off your first order this week! locked_parents: [] lockable_children: [] - uuid: c3333333-d444-4eee-8fff-aaaaaaaa0003 asset_type: visual_editor shareable_name: promo_banner_autumn display_name: Autumn Promo Banner archived: false author: Marketing Team email: marketing@example.com templates: [] template_count: 0 updated_at: '2025-08-25T09:15:00.000Z' content: "
\n

Autumn Sale

\n

Save up to 30% on selected items.

\n Shop Now\n
" locked_parents: [] lockable_children: [] '400': description: Bad request - The request was invalid or cannot be otherwise served. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - Can happen due to resource conflicts. Re-try with exponential backoff. '409': description: Conflict error, please retry - The request could not be completed due to a conflict with the current state of the target resource, re-try with exponential backoff. '413': description: Payload too large - The server is refusing to process a request because the request payload is larger than the server is willing or able to process. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Rate limit exceeded - Too many requests. '500': description: Internal Server Error - Please contact Blueshift for more information. '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff. '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff. '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff. post: summary: Create a shared asset description: Use this endpoint to create a shared asset. tags: - Shared assets security: - user_api_auth: [] requestBody: content: application/json: schema: type: object required: - display_name - content - asset_type properties: display_name: type: string description: Human-readable name for the asset. Used to generate the shareable_name if not provided. example: Welcome Email Header content: type: string description: The actual content of the asset. For HTML assets, provide HTML markup. For Subject assets, provide plain text. example:

Welcome to our store!

asset_type: type: string description: Type of asset to create. Must be either 'html' or 'subject'. Cannot be changed after creation. enum: - html - subject example: html plain_text: type: string description: Plain text version of the content. Only applicable for HTML assets. If not provided, Blueshift will auto-generate it. example: Welcome to our store! is_plain_text_custom: type: boolean description: Set to true if providing a custom plain_text version, false to auto-generate. Only applicable for HTML assets. example: true author: type: string description: Email address of the user to attribute as the asset's author. Must be a valid user in the account. If omitted or invalid, defaults to the account's primary user. example: john.doe@example.com examples: html_asset: summary: Create HTML asset value: display_name: Welcome Email Header content:

Welcome to our store!

asset_type: html html_asset_with_plain_text: summary: Create HTML asset with custom plain text value: display_name: Product Announcement content:

New Product Launch

Check out our latest collection.

asset_type: html plain_text: New Product Launch - Check out our latest collection. is_plain_text_custom: true subject_asset: summary: Create Subject asset value: display_name: Welcome Subject Line content: Welcome to our community! asset_type: subject html_asset_with_author: summary: Create HTML asset attributed to an author value: display_name: Welcome Email Header content:

Welcome to our store!

asset_type: html author: john.doe@example.com responses: '200': description: OK content: application/json: schema: type: object properties: uuid: type: string description: Unique identifier for the shared asset. Use this value for updates. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 asset_type: type: string description: Type of the asset. example: html shareable_name: type: string description: 'Auto-generated unique identifier based on display_name. Format: bsft_. Spaces become underscores, special characters are removed.' example: bsft_Welcome_Email_Header display_name: type: string description: Human-readable name for the asset. example: Welcome Email Header author: type: string description: Name of the user who created the asset. example: John Doe email: type: string description: Email of the user who created the asset. example: john.doe@example.com content: type: string description: The actual content of the asset. example:

Welcome to our store!

plain_text: type: - string - 'null' description: Plain text version of the content. Null if not provided for HTML assets or not applicable for Subject assets. example: null is_plain_text_custom: type: - boolean - 'null' description: Indicates whether plain text is custom (true) or auto-generated (false). Null for Subject assets. example: false updated_at: type: string format: date-time description: Timestamp of when the asset was last updated (ISO 8601 format). example: '2026-01-28T08:00:00.000Z' tag_data: type: string description: Tags associated with the asset. example: Regions:NA,EU,APAC,LATAM,GreaterChina examples: html_asset_response: summary: HTML asset created value: uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890 asset_type: html shareable_name: bsft_Welcome_Email_Header display_name: Welcome Email Header author: John Doe email: john.doe@example.com content:

Welcome to our store!

plain_text: null is_plain_text_custom: false updated_at: '2026-01-28T08:00:00.000Z' tag_data: Regions:NA,EU,APAC,LATAM,GreaterChina subject_asset_response: summary: Subject asset created value: uuid: b2c3d4e5-f6a7-8901-bcde-f12345678901 asset_type: subject shareable_name: bsft_Welcome_Subject_Line display_name: Welcome Subject Line author: John Doe email: john.doe@example.com content: Welcome to our community! plain_text: null is_plain_text_custom: null updated_at: '2026-01-28T08:00:00.000Z' tag_data: Regions:NA,EU,APAC,LATAM,GreaterChina '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: 'HTTP Basic: Access denied.' '422': description: 'Unprocessable Entity - The request was well-formed but contains validation errors. Common causes: missing required fields (display_name, content, asset_type), duplicate shareable_name, or empty values.' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: title: type: string example: shareable_name detail: type: string example: 'Shareable_name: This template name is already in use, please use a different name' meta: type: object properties: combine_errors: type: boolean example: false no_toast: type: boolean example: false unformatted: type: object additionalProperties: type: array items: type: string examples: duplicate_name: summary: Duplicate shareable_name value: errors: - title: shareable_name detail: 'Shareable_name: This template name is already in use, please use a different name' meta: combine_errors: false no_toast: false unformatted: shareable_name: - This template name is already in use, please use a different name blank_field: summary: Missing required field value: errors: - title: shareable_name detail: 'Shareable_name: can''t be blank' meta: combine_errors: false no_toast: false unformatted: shareable_name: - can't be blank '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: status: type: string example: '500' error: type: string example: Internal Server Error /api/v1/shared_assets/{uuid}.json: put: summary: Update a shared asset description: Use this endpoint to update a shared asset. tags: - Shared assets security: - user_api_auth: [] parameters: - in: path required: true name: uuid description: The UUID of the shared asset to update. This value is returned when you create an asset. schema: type: string example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 requestBody: content: application/json: schema: type: object properties: display_name: type: string description: Human-readable name for the asset. Can be updated at any time. example: Updated Welcome Header content: type: string description: The actual content of the asset. For HTML assets, provide HTML markup. For Subject assets, provide plain text. example:

Welcome to our updated store!

plain_text: type: string description: Plain text version of the content. Only applicable for HTML assets. example: Welcome to our updated store! is_plain_text_custom: type: boolean description: Set to true if providing a custom plain_text version, false to auto-generate. Only applicable for HTML assets. example: true examples: update_html_asset: summary: Update HTML asset value: display_name: Updated Welcome Header content:

Welcome to our updated store!

update_html_with_plain_text: summary: Update HTML asset with custom plain text value: display_name: Updated Product Announcement content:

New Product Launch Updated

Check out our latest collection.

plain_text: New Product Launch Updated - Check out our latest collection. is_plain_text_custom: true update_subject_asset: summary: Update Subject asset value: display_name: Updated Welcome Subject content: Welcome to our growing community! responses: '200': description: OK content: application/json: schema: type: object properties: uuid: type: string description: Unique identifier for the shared asset. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 asset_type: type: string description: Type of the asset. Cannot be changed after creation. example: html shareable_name: type: string description: Auto-generated unique identifier. Cannot be changed after creation. example: bsft_Welcome_Email_Header display_name: type: string description: Human-readable name for the asset. example: Updated Welcome Header author: type: string description: Name of the user who last updated the asset. example: John Doe email: type: string description: Email of the user who last updated the asset. example: john.doe@example.com content: type: string description: The actual content of the asset. example:

Welcome to our updated store!

plain_text: type: - string - 'null' description: Plain text version of the content. Null if not provided for HTML assets or not applicable for Subject assets. example: null is_plain_text_custom: type: - boolean - 'null' description: Indicates whether plain text is custom (true) or auto-generated (false). Null for Subject assets. example: false updated_at: type: string format: date-time description: Timestamp of when the asset was last updated (ISO 8601 format). example: '2026-01-28T09:30:00.000Z' tag_data: type: string description: Tags associated with the asset. example: Regions:NA,EU,APAC,LATAM,GreaterChina examples: html_asset_updated: summary: HTML asset updated value: uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890 asset_type: html shareable_name: bsft_Welcome_Email_Header display_name: Updated Welcome Header author: John Doe email: john.doe@example.com content:

Welcome to our updated store!

plain_text: null is_plain_text_custom: false updated_at: '2026-01-28T09:30:00.000Z' tag_data: Regions:NA,EU,APAC,LATAM,GreaterChina subject_asset_updated: summary: Subject asset updated value: uuid: b2c3d4e5-f6a7-8901-bcde-f12345678901 asset_type: subject shareable_name: bsft_Welcome_Subject_Line display_name: Updated Welcome Subject author: John Doe email: john.doe@example.com content: Welcome to our growing community! plain_text: null is_plain_text_custom: null updated_at: '2026-01-28T09:30:00.000Z' tag_data: NA,EU,APAC,LATAM,GreaterChina '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: 'HTTP Basic: Access denied.' '404': description: Not Found - The specified shared asset UUID does not exist. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: 'Unprocessable Entity - The request was well-formed but contains validation errors. Common causes: duplicate shareable_name or empty values.' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: title: type: string example: shareable_name detail: type: string example: 'Shareable_name: This template name is already in use, please use a different name' meta: type: object properties: combine_errors: type: boolean example: false no_toast: type: boolean example: false unformatted: type: object additionalProperties: type: array items: type: string examples: validation_error: summary: Validation error value: errors: - title: content detail: 'Content: can''t be blank' meta: combine_errors: false no_toast: false unformatted: content: - can't be blank '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: status: type: string example: '500' error: type: string example: Internal Server Error components: securitySchemes: user_api_auth: type: http scheme: basic event_api_auth: type: http scheme: basic