Assets API

Assets API

The Assets API can be used to manage assets in bulk.

What to know

Necessary permissions

To access assets through the Assets API, you must have the following:

See API Keys for more information.

Delete assets

You can delete assets by ID, URL or GraphQL.

By ID

Make the following request, replacing ASSET_ID, PUBLIC_API_KEY, and PRIVATE_API_KEY with your asset ID and your space's public and private key.

curl --location --request DELETE \
'https://cdn.builder.io/api/v1/assets/ASSET_ID&apiKey=PUBLIC_API_KEY' \
 --header 'Authorization: Bearer PRIVATE_API_KEY'

By URL

Make the following request, replacing ENCODED_ASSET_URL, PUBLIC_API_KEY, and PRIVATE_API_KEY with your asset's encoded URL and your space's public and private key.

curl --location --request DELETE \
'https://cdn.builder.io/api/v1/assets/by-url?url=ENCODED_ASSET_URL&apiKey=PUBLIC_API_KEY' \
 --header 'Authorization: Bearer PRIVATE_API_KEY'

Using GraphQL

Delete assets using GraphQL with the deleteAsset mutation. This approach requires only the asset ID and private API key.

Make the following request, replacing ASSET_ID and YOUR_BUILDER_PRIVATE_KEY with the asset ID and private key:

curl --location 'https://cdn.builder.io/api/v2/admin' \
 --header 'x-cdn-host: cdn.builder.io' \
 --header 'Authorization: Bearer YOUR_BUILDER_PRIVATE_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
"query": "mutation ($id: String!) { deleteAsset (id: $id) }",
"variables": { "id": "YOUR_ASSET_ID" }
}'

An example GraphQL mutation:

mutation DeleteAsset($id: String!) {
deleteAsset(id: $id)
}

For more GraphQL mutations and queries, see Admin GraphQL Schema.

Access your asset's URL

To access your asset's URL:

  1. Visit your Asset Library and right-click on an image
  2. Select Copy Image Address

You also receive the image URL when using the Upload API.

Note: Your asset URL may not have any parameters attached to it. For example, parameters like ?width=500&height=500 should be removed.

Encode your asset's URL

The asset's URL must be encoded. An encoded URL will look like the following:

https%3A%2F%2Fcdn.builder.io%2Fapi%2Fv1%2Fimage%2Fassets%252F03e666806e034ea99ba3d09deba16592%252Fac9ba45aa4d3412dbe177edacf4034a0

Note that the asset URL you retrieve from Builder may already be partially encoded. You can tell by the presence of %2F characters within the URL.

Leave these characters within the URL when encoding.

Encode your URL

To encode your URL, use the encodeURIComponent() built-in JavaScript function.

encodeURIComponent("YOUR_URL");

Note: The asset URL you retrieve from Builder may already be partially encoded. You can tell by the presence of %2F characters within the URL.

Leave these characters within the URL when encoding.

Query assets

Sort assets

Use the following query to sort your assets by a particular key, such as the asset's name.

const response = await adminSDK
.query({
assets: [
{
input: {
sort: {
name: "-1"// or 1 }
}
},
{
id: true,
name: true,
url: true,
bytes: true,
lastUsed: true,
type: true,
folders: true }
}
]
});

Response

{
"data": {
"assets": [
{
"id": "...",
"name": "My Image",
"url": "...",
"bytes": 380892,
"lastUsed": 1745956615894,
"type": "image/jpeg",
"folders": ["folder-id-1", "folder-id-2"],
"createdDate": "2024-01-15T10:30:00Z" }
]
}
}

Query

query {
assets(input: {
sort: {
name: "ascending" }
}) {
id
name
url
bytes
lastUsed
type folders
}
}

Response

{
"data": {
"assets": [
{
"id": "...",
"name": "A sunset in Greece",
"url": "...",
"bytes": 380892,
"lastUsed": 1745956615894,
"type": "image/jpeg",
"folders": ["folder-id-1"]
}
]
}
}

Filter assets by type

To filter assets by media type (such as images, videos, or specific formats), use the type field. Note that this corresponds to the MIME type of the asset.

const response = await adminSDK
.query({
assets: [
{
input: {
query: {
type: { $eq: "image/svg+xml" }
},
sort: {
createdDate: "descending" }
}
},
{
id: true,
name: true,
url: true,
type: true,
folders: true,
createdDate: true }
}
]
});

Response

{
"data": {
"assets": [
{
"id": "...",
"name": "My Icon",
"url": "...",
"type": "image/svg+xml",
"folders": ["folder-id-1"],
"createdDate": "2024-01-15T10:30:00Z" }
]
}
}

Common asset types:

Filter assets by folder

To filter assets by folder, use the folders field with the folder ID. Assets can belong to multiple folders, so folders is an array field.

const response = await adminSDK
.query({
assets: [
{
input: {
query: {
folders: { $in: ["your-folder-id"] }
},
sort: { createdDate: "descending" }
}
},
{
id: true,
name: true,
url: true,
type: true,
folders: true,
createdDate: true }
}
]
});

Response

{
"data": {
"assets": [
{
"id": "...",
"name": "Folder Asset",
"url": "...",
"type": "image/png",
"folders": ["your-folder-id"],
"createdDate": "2024-01-15T10:30:00Z" }
]
}
}

Query

query {
assets(input: {
query: {
folders: { $in: ["your-folder-id"] }
},
sort: {
createdDate: "descending" }
}) {
id
name
url
type folders
createdDate
}
}

Response

Filter assets by type and folder

You can combine multiple filters to get more specific results. For example, to get all SVG images from a specific folder:

const response = await adminSDK
.query({
assets: [
{
input: {
query: {
type: { $eq: "image/svg+xml" },
folders: { $in: ["your-folder-id"] }
},
sort: { createdDate: "descending" },
limit: 50 }
},
{
id: true,
name: true,
url: true,
type: true,
folders: true,
createdDate: true }
}
]
});

Response

{
"data": {
"assets": [
{
"id": "...",
"name": "My SVG Icon",
"url": "...",
"type": "image/svg+xml",
"folders": ["your-folder-id"],
"createdDate": "2024-01-15T10:30:00Z" }
]
}
}

Query

query {
assets(input: {
query: {
type: { $eq: "image/svg+xml" },
folders: { $in: ["your-folder-id"] }
},
sort: {
createdDate: "descending" },
limit: 50 }) {
id
name
url
type folders
createdDate
}
}

Response

Using variables for dynamic queries

const input = {
query: {
type: { $eq: "image/svg+xml" },
folders: { $in: ["your-folder-id"] }
},
sort: {
createdDate: "descending" },
limit: 20};

const response = await adminSDK
.query({
assets: [
{ input },
{
id: true,
name: true,
url: true,
type: true,
folders: true,
createdDate: true,
bytes: true,
lastUsed: true }
}
]
});

For more complex filtering, you can use GraphQL variables:

query ($input: QueryAssetsInput!) {
assets(input: $input) {
id
name
url
type folders
createdDate
bytes
lastUsed
}
}

Variables

{
"input": {
"query": {
"type": { "$eq": "image/svg+xml" },
"folders": { "$in": ["your-folder-id"] }
},
"sort": {
"createdDate": -1 },
"limit": 20 }
}

Available query operators

Example with multiple operators:

const response = await adminSDK
.query({
assets: [
{
input: {
query: {
type: { $in: ["image/jpeg", "image/png"] },
name: { $regex: "logo" },
folders: { $exists: true }
}
}
},
{
id: true,
name: true,
url: true,
type: true,
folders: true }
}
]
});

For more complex filtering, you can use GraphQL variables:

query ($input: QueryAssetsInput!) {
assets(input: $input) {
id
name
url
type folders
createdDate
bytes
lastUsed
}
}

Variables

{
"input": {
"query": {
"type": { "$in": ["image/jpeg", "image/png"] },
"name": { "$regex": "logo" },
"folders": { "$exists": true }
}
}

This query returns jpeg or png images that have "logo" in their name and belong to at least one folder.

What's next

Programmatically upload files with the Upload API or learn more about how to access images with the Image API.