# Assets API

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

## What to know

- Delete assets programmatically via the Assets API
- Encode asset URLs to ensure functional API calls

## Necessary permissions

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

- A **Public API Key**
- A **Space Private Key**

See [API Keys](/content/c/docs/using-your-api-key/index.html) 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.

```bash
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.

```bash
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:

```bash
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:

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

For more GraphQL mutations and queries, see [Admin GraphQL Schema](/content/c/docs/admin-graphql-schema/index.html).

#### 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](/content/c/docs/upload-api/index.html).

**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.

```javascript
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.

```javascript
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**

```json
{
"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**

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

**Response**

```json
{
"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.

```javascript
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**

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

Common asset types:

- `image/jpeg`: `jpeg` images
- `image/png`: `png` images
- `image/svg+xml`: `svg` images
- `image/gif`: `gif` images
- `image/webp`: `webp` images
- `video/mp4`: `mp4` videos
- `application/pdf`: `pdf` documents

## 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.

```javascript
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**

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

**Query**

```graphql
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:

```javascript
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**

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

**Query**

```graphql
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

```javascript
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:

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

**Variables**

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

## Available query operators

- `$eq`: equal
- `$ne`: not equal
- `$in`: in array
- `$nin`: not in array
- `$exists`: field exists
- `$regex`: regular expression match

Example with multiple operators:

```javascript
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:

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

**Variables**

```json
{
"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](/content/c/docs/upload-api/index.html) or learn more about how to access images with the [Image API](/content/c/docs/image-api/index.html).