---
title: "List editable resources that use an asset"
method: GET
path: "/v1/assets/{asset_id}/references"
tags: ["assets"]
---

# List editable resources that use an asset

`GET /v1/assets/{asset_id}/references`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/assets/{asset_id}/references`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Returns editable resources that reference this asset. Each entry indicates whether
the reference appears in the resource's draft, published version, or both. Results
reflect the latest saved versions, so they exclude unsaved editor changes and older
published versions.

Only resources you have permission to read are included. Email-template references
require `email_management:read` in addition to `assets:read`. Hidden resources do not
affect the `truncated` flag.

Removing an asset does not break existing references because its original URL keeps
serving. Use this list to find content that should reference a replacement asset.

## Path parameters

- `asset_id` string, required

## Headers

- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `200`

The resources that reference the asset.

- AssetReferenceList
  - `data` AssetReference[], required
    - `resource_type` string, required: What kind of resource this is. New kinds appear as other products start using the media library, so treat an unfamiliar value as a resource this client does not know how to link to rather than as an error.
    - `resource_id` string, required: The resource's own identifier, carrying that resource's prefix (`emt_` for an email template), for linking straight to it.
    - `resource_name` string, required: The resource's current display name, read when you list references.
    - `usage` string, required: Which copy of a resource uses an asset. - `draft`: it is not reaching anyone yet. - `published`: the change has to be published before recipients see it. - `both`: the asset is used in both copies.
  - `truncated` boolean, required: True when more resources use this asset than one response can carry, so the list is a partial answer. Replace the asset's usages you can see, then list again to find the rest.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `501`: The operation is not supported

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)