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:

{
  "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:

{
  "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 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, the default number of results per page is 100.

Example

Request:

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

Response:

{
  "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:

{
  "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:

{
  "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 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

Query parameters

fields

include

order

page

per

search

sort_by

Was this helpful?

`fields`

`include`

`order`

`page`

`per`

`search`

`sort_by`