List shared assets

API at a glance

Description: Retrieves shared assets, supporting filters and pagination.

Key query parameters:

asset_type[] (html, rich_text, visual_editor, subject)
display_name (substring match)
archived (0 = active, 1 = archived, omit = all)
Pagination with page and per_page

Authentication & testing

Testing the API on this page

How to try it here

Use your User API Key as the Username (leave Password blank).

Select the appropriate API endpoint based on your Blueshift region.

Enter the necessary parameters and click Try It to run the request.

Authentication using Base64 encoding

Note for developers

API requests require authentication using HTTP Basic Authentication with an API key. The API key serves as the username, while the password field should be left empty. The format to encode is: your_api_key: (note the trailing colon).

This string must be Base64-encoded and included in the request's Authorization header as follows:

Authorization: Basic encoded_value

You can generate the encoded value using a trusted Base64 encoder.

Postman collection

Try it with Postman: Explore the API using Blueshift's Postman collection.

Things to know before you start

If no query parameters are applied, the API retrieves all shared assets in the account, including both active and archived assets across all supported types (html, rich_text, visual_editor, and subject).

Request parameters

Check out the request parameters

Name	Type	Required	Description	Example
`asset_type[]`	array of strings	No	Filter by one or more asset types. Repeat the parameter for multiple values. Allowed values: `html`, `rich_text`, `visual_editor`, `subject`.	`asset_type[]=html&asset_type[]=visual_editor`
`display_name`	string	No	Returns assets whose display name contains the specified substring. An empty string returns all.	`Banner`
`archived`	integer	No	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`).	`0`
`page`	integer	No	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.	`0`
`per_page`	integer	No	The number of results to return per page.	`25`

Example requests & responses

Example 1 — Get active HTML + Visual Editor assets

Intent: Fetch only active shared assets of types html and visual_editor, limited to 2 results from the first page.

curl --location --globoff \
'https://api.getblueshift.com/api/v1/shared_assets.json?asset_type[]=html&asset_type[]=visual_editor&archived=0&per_page=2&page=0&order_by=updated_at&reverse=true' \
--header 'accept: application/json' \
--header 'authorization: Basic <API_KEY>'

[
  {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-1234567890ef",
    "asset_type": "html",
    "shareable_name": "footer_block",
    "display_name": "Footer Block",
    "archived": false,
    "author": "Content Team",
    "email": "[email protected]",
    "templates": [],
    "template_count": 0,
    "updated_at": "2025-08-28T12:00:00.000Z",
    "content": "<table><tr><td>Footer HTML content</td></tr></table>",
    "locked_parents": [],
    "lockable_children": []
  },
  {
    "uuid": "b2c3d4e5-f6a7-8901-bcde-2345678901fg",
    "asset_type": "visual_editor",
    "shareable_name": "promo_banner",
    "display_name": "Promo Banner",
    "archived": false,
    "author": "Design Team",
    "email": "[email protected]",
    "templates": [],
    "template_count": 0,
    "updated_at": "2025-08-28T15:30:00.000Z",
    "content": "<div style=\"text-align:center;\">Big Sale</div>",
    "locked_parents": [],
    "lockable_children": []
  }
]

Example 2 — Get subject assets matching a display name

Intent: Return subject-type assets with a display name containing “Welcome”, newest first.

curl --location --globoff \
'https://api.getblueshift.com/api/v1/shared_assets.json?asset_type[]=subject&display_name=Welcome&per_page=2&page=0&order_by=updated_at&reverse=true' \
--header 'accept: application/json' \
--header 'authorization: Basic <API_KEY>'

[
  {
    "uuid": "c3d4e5f6-a7b8-9012-cdef-3456789012gh",
    "asset_type": "subject",
    "shareable_name": "welcome_subject_v2",
    "display_name": "Welcome Subject v2",
    "archived": false,
    "author": "Copy Team",
    "email": "[email protected]",
    "templates": [],
    "template_count": 0,
    "updated_at": "2025-08-29T09:45:00.000Z",
    "content": "Welcome aboard! Here’s your quick start.",
    "locked_parents": [],
    "lockable_children": []
  },
  {
    "uuid": "d4e5f6a7-b8c9-0123-def4-4567890123hi",
    "asset_type": "subject",
    "shareable_name": "welcome_subject_offer",
    "display_name": "Welcome Subject – Special Offer",
    "archived": false,
    "author": "Copy Team",
    "email": "[email protected]",
    "templates": [],
    "template_count": 0,
    "updated_at": "2025-08-29T08:20:00.000Z",
    "content": "Thanks for joining! Enjoy 15% off your first purchase.",
    "locked_parents": [],
    "lockable_children": []
  }
]

API error responses

Status code	Description
400	Bad request – The request is invalid.
404	Not found – The requested resource does not exist or is unavailable.
409	Conflict – The request conflicts with the current state of the resource. Retry with exponential backoff.
413	Payload too large – The request size exceeds the server limit.
429	Too many requests – Rate limit exceeded. Retry with exponential backoff.
500	Internal server error – An unexpected error occurred on the server.
502	Bad gateway – Temporary error. Retry with exponential backoff.
503	Service unavailable – The service is temporarily unavailable. Retry with exponential backoff.
504	Gateway timeout – The server took too long to respond. Retry with exponential backoff.