# Query parameters

Many API endpoints accept some or all of the following URL parameters in order for you to get more information or specify what exactly you would like to retrieve.

This section aims to explain generally how to use each parameter. See the section related to the exact API call you are doing in order to find out its valid parameters and accepted values.

> **WARNING:** Using these can slow down the API response time.


## `fields`

`fields` is an optional query parameter that takes comma-separated list of field names with no spaces. These additional requested fields are returned as attributes on the fetched resource(s). Make sure to read the documentation for each endpoint to know which non-default attribute fields can be requested.

**Example**

Request:


```
GET /brandfolders/{brandfolder_id}/assets?fields=cdn_url,updated_at
```

Response:


```json
{
  "data": [
    {
      "id": "oqgkkd-fr5iv4-443db",
      "type": "generic_files",
      "attributes": {
        "name": "Brandfolder Logo",
        "description": "Brandfolder's logo in print ready form",
        "thumbnail_url": "https://example.com/thumbnail1/example.jpeg?Expires=1624742369",
        "approved": true,
        "cdn_url": "https://cdn.bfldr.com/example/asset/example1.png?auto=webp&format=png",
        "updated_at": "2018-09-11T20:31:34.858Z"
      }
    },
    {
      "id": "oqh4xl-ci1u7c-emfa7g",
      "type": "generic_files",
      "attributes": {
        "name": "Facebook Banner - Large",
        "description": "Brandfolder banner optimized for Facebook",
        "thumbnail_url": "https://example.com/thumbnail2/example.jpeg?Expires=1624742369",
        "approved": false,
        "cdn_url": "https://cdn.bfldr.com/example/asset/example1.png?auto=webp&format=png",
        "updated_at": "2018-09-11T20:31:34.858Z"
      }
    }
  ],
  "meta": {
    "total_count": 2
  }
}
```

## `include`

`include` is an optional query parameter used to request records that are related to the resource(s) you are fetching. It will add any existing related records to an `included` array in the JSON response. Make sure to read the documentation for each endpoint to know which relationships are valid to include with each request. Values must be submitted as a comma-separated list of supported record types with no spaces.

**Example**

Request:


```
GET /brandfolders/{brandfolder_id}/assets?include=brandfolder,section,attachments
```

Response:


```json
{
  "data": [
    {
      "id": "oqgkkd-fr5iv4-443db",
      "type": "generic_files",
      "attributes": {
        "name": "Brandfolder Logo",
        "description": "Brandfolder's logo in print ready form",
        "thumbnail_url": "https://example.com/thumbnail1/example1.jpeg?Expires=1624742369",
        "approved": true
      },
      "relationships": {
        "brandfolder": {
          "data": {
            "id": "pdmjei-bhg70o-4ap88",
            "type": "brandfolders"
          }
        },
        "section": {
          "data": {
            "id": "pdmjmp-3zcfgo-boa4xr",
            "type": "sections"
          }
        },
        "attachments": {
          "data": [
            {
              "id": "pewron-9f9uaw-2em6u7",
              "type": "attachments"
            }
          ]
        }
      }
    },
    {
      "id": "oqh4xl-ci1u7c-emfa7g",
      "type": "generic_files",
      "attributes": {
        "name": "Facebook Banner - Large",
        "description": "Brandfolder banner optimized for Facebook",
        "thumbnail_url": "https://example.com/thumbnail137/example.jpeg?Expires=1624742369",
        "approved": false
      },
      "relationships": {
        "brandfolder": {
          "data": {
            "id": "pdmjei-bhg70o-4ap88",
            "type": "brandfolders"
          }
        },
        "section": {
          "data": {
            "id": "pdmjmp-3zcfgo-boa4xr",
            "type": "sections"
          }
        },
        "attachments": {
          "data": [
            {
              "id": "pewron-e23is0-2x6fbq",
              "type": "attachments"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "id": "pdmjei-bhg70o-4ap88",
      "type": "brandfolders",
      "attributes": {
        "name": "Example Brandfolder",
        "tagline": "This is an awesome Brandfolder",
        "privacy": "stealth",
        "slug": "example-brandfolder"
      }
    },
    {
      "id": "pdmjmp-3zcfgo-boa4xr",
      "type": "sections",
      "attributes": {
        "name": "Logo Section",
        "default_asset_type": "GenericFile",
        "position": 0
      }
    },
    {
      "id": "pewron-9f9uaw-2em6u7",
      "type": "attachments",
      "attributes": {
        "mimetype": "image/png",
        "filename": "1example.png",
        "size": 1603,
        "width": 126,
        "height": 75,
        "url": "https://example.com/pewron-9f9uaw-2em6u7/original/1example.png",
        "position": 0
      }
    },
    {
      "id": "pewron-e23is0-2x6fbq",
      "type": "attachments",
      "attributes": {
        "mimetype": "image/png",
        "filename": "137example.png",
        "size": 1539,
        "width": 134,
        "height": 187,
        "url": "https://example.com/pewron-e23is0-2x6fbq/original/137example.png",
        "position": 0
      }
    }
  ],
  "meta": {
    "total_count": 2
  }
}
```

## `order`

`order` is an optional query parameter for setting the sort order of results, based on the `sort_by` attribute.

Here are the supported `order` values:

- `ASC` (ascending)
- `DESC` (descending)


> **Important:** When using the `order` query parameter, you must include a [`sort_by`](#sort_by) query parameter set to the attribute to order by.


**Example**

Return assets sorted by their name in reverse-alphabetical order.

Request:


```
GET /brandfolders/{brandfolder_id}/assets?sort_by=name&order=DESC
```

## `page`

`page` is an optional query parameter used for pagination. It specifies which page of results you would like to receive back.

> **Important:** Page numbering starts at `1`.


> **Note:** Unless you explicitly set a value for [`per`](#per), the default number of results per page is `100`.


**Example**

Request:


```
GET /brandfolders/{brandfolder_id}/assets?page=3&per=2
```

Response:


```json
{
  "data": [
    {
      "id": "oqgkkd-fr5iv4-443db",
      "type": "generic_files",
      "attributes": {
        "name": "Brandfolder Logo",
        "description": "Brandfolder's logo in print ready form",
        "thumbnail_url": "https://example.com/thumbnail1/example.jpeg?Expires=1624742369",
        "approved": true
      }
    },
    {
      "id": "oqh4xl-ci1u7c-emfa7g",
      "type": "generic_files",
      "attributes": {
        "name": "Facebook Banner - Large",
        "description": "Brandfolder banner optimized for Facebook",
        "thumbnail_url": "https://example.com/thumbnail2/example.jpeg?Expires=1624742369",
        "approved": false
      }
    }
  ],
  "meta": {
    "total_count": 17
  }
}
```

## `per`

`per` is an optional query parameter used for pagination, or simply to limit or increase the amount of results you would like to receive back from your request. The value you set for `per` is the maximum number for records you will get, although more may exist (as denoted by the `meta.total_count` value). The default value is `100` and maximum is `3000`.

**Example**

Request:


```
GET /brandfolders/{brandfolder_id}/assets?per=2
```

Response:


```json
{
  "data": [
    {
      "id": "oqgkkd-fr5iv4-443db",
      "type": "generic_files",
      "attributes": {
        "name": "Brandfolder Logo",
        "description": "Brandfolder's logo in print ready form",
        "thumbnail_url": "https://example.com/thumbnail1/example.jpeg?Expires=1624742369",
        "approved": true
      }
    },
    {
      "id": "oqh4xl-ci1u7c-emfa7g",
      "type": "generic_files",
      "attributes": {
        "name": "Facebook Banner - Large",
        "description": "Brandfolder banner optimized for Facebook",
        "thumbnail_url": "https://example.com/thumbnail2/example.jpeg?Expires=1624742369",
        "expiration_date": "2018-09-11T20:31:34.858Z",
        "approved": false
      }
    }
  ],
  "meta": {
    "total_count": 17
  }
}
```

## `search`

`search` is an optional query parameter that allows you to fetch only the records that match your query. It works just like the standard search bar does on the Brandfolder website. Appropriate values for searching for Assets or Attachments can be found at Search in Brandfolder. Only resources matching the query are returned.

> **Important:** Make sure to URL-encode your search parameter value.


**Example**

Request:


```
GET /brandfolders/{brandfolder_id}/assets?search=extension:png
```

Response:


```json
{
  "data": [
    {
      "id": "oqgkkd-fr5iv4-443db",
      "type": "generic_files",
      "attributes": {
        "name": "Brandfolder Logo",
        "description": "Brandfolder's logo in print ready form",
        "thumbnail_url": "https://example.com/thumbnail1/example.png?Expires=1624742369",
        "approved": true,
        "cdn_url": "https://cdn.bfldr.com/example/asset/example1.png?auto=webp&format=png",
        "updated_at": "2018-09-11T20:31:34.858Z"
      }
    },
    {
      "id": "oqh4xl-ci1u7c-emfa7g",
      "type": "generic_files",
      "attributes": {
        "name": "Facebook Banner - Large",
        "description": "Brandfolder banner optimized for Facebook",
        "thumbnail_url": "https://example.com/thumbnail2/example.png?Expires=1624742369",
        "approved": false,
        "cdn_url": "https://cdn.bfldr.com/example/asset/example1.png?auto=webp&format=png",
        "updated_at": "2018-09-11T20:31:34.858Z"
      }
    }
  ],
  "meta": {
    "total_count": 2
  }
}
```

## `sort_by`

`sort_by` is an optional query parameter for sorting results based on a specific attribute.

Here are the supported attributes:

- `name`
- `score`
- `position`
- `updated_at`
- `created_at`


> **Important:** When using `sort_by`, you must also include the [`order`](#order) parameter to specify the sort direction: `ASC` for ascending or `DESC` for descending.


**Example**

Return assets sorted alphabetically by their name.

Request:


```
GET /brandfolders/{brandfolder_id}/assets?sort_by=name&order=ASC
```