Search API reference

You can query Adobe Stock for assets that meet your specified search criteria. You can filter the results, specify the sort order in which the results are returned, and choose how many assets to return for each page of results.

Search requests

A request using the Stock Search API retrieves a list of assets from Adobe Stock that matches a set of search and filter values. A maximum of 100 assets can be returned from one request. This is a paginated interface that you can call multiple times to retrieve the full list.

For a guide to usage and additional examples, see Creating Adobe Stock applications.

About search and filter criteria

Search commands have three formats:

1. Search parameters. In general, search parameters identify asset information for values that cannot be predetermined, such as ID numbers or keywords. Parameters for searches look like this:

   search_parameters[*search_item*]=*value*

   For example:

   search_parameters[words]=dog big happy

   Search parameters are treated as AND. For example, you could combine [words] and [creator_id] to search for assets created by a specific creator that have the specified keywords.

   search_parameters[words]=dog big happy&search_parameters[creator_id]=12345

   Tip: You must specify at least one search_parameters value for each Search.

2. Filtering values. These optional qualifiers specify which of the found assets to return. In general, filters identify asset information that has a known set of values, such as true/false or file type. Parameters for filtering look like this:

   search_parameters[filters][{FILTER NAME}]={VALUE}

   For example:

   search_parameters[filters][orientation]=horizontal

   You can specify multiple filtering values for content_type, template_type_id, and template_category_id; search returns assets that match any of those values. The remaining filters are treated as AND.

3. Response control. In addition to the filter and search mechanisms above, search queries by default return a fixed number of fields. To increase or decrease the scope of the response data, add one or more result_columns[] to the query. For example, using ?result_columns[]=id by itself will return only content IDs.

{
    "id": 108289885
},
{
    "id": 173919253
},

Chain together multiple result_columns[] commands to get exactly the results you want.

result_columns[]=id&result_columns[]=title&result_columns[]=thumbnail_url

{
    "id": 108289885,
    "title": "Vector illustration of colorful horse, unicorn, or pony.",
    "thumbnail_url": "https://as1.ftcdn.net/jpg/01/08/28/98/500_F_108289885_zxdW0u0ds2oI69ZiLaON3kfhM2OLxdin.jpg"
},
{
    "id": 173919253,
    "title": "Isolated cute watercolor unicorn clipart. Nursery unicorns illustration. Princess rainbow unicorns poster. Trendy pink cartoon horse.",
    "thumbnail_url": "https://as1.ftcdn.net/jpg/01/73/91/92/500_F_173919253_ivNTXG10bJKxSPRkxiAeaZZOjaWr5SBe.jpg"
},

See Responses, below.

Authentication

An Authorization header is not required. If you do not pass a valid bearer token in the Authorization header, you can search within Adobe Stock and access preview versions of assets, but the API will not return licensing requirements or give you the licensed status for the assets. Requests made in this way are essentially anonymous, with no notion of the user making the request.

If you do pass a valid token, then the Adobe Stock service returns the license state and licensed URL for each asset. See API authentication.

Request headers

See API authentication and Headers for Stock API calls for details about header content.

• Required headers: x-Product, x-api-key
• Optional headers: Authorization (required to view license state), X-Request-Id

URL parameters

Pass the following URL parameters with the GET request.

Tip: The only required parameter is at least one search_parameters[].

Responses

The Adobe Stock Search service returns information about all found assets that also match the filtering criteria.

Tip: Assets on Adobe Stock can be added, changed, or removed by other parties between your API calls. Therefore, the total number of matching assets and the selection of assets can change between successive calls to Search.

<!-- Start include -->

data-src=./search-files-responses.md

<!-- End include -->

Example queries and responses

This example searches for assets that have the keyword "dog" and returns no more than the first two matches.

GET /Rest/Media/1/Search/Files?locale=en_US&search_parameters[words]=dogs&search_parameters[limit]=2 HTTP/1.1
Host: stock.adobe.io
X-Product: MySampleApp/1.0
x-api-key: MyApiKey

The preceding request returns two asset descriptions. nb_results shows that 399,884 assets currently match the keyword "dog".

{
 "nb_results": 399884,
 "files": [
   {
     "id": 86760419,
     "title": "German Shepherd Dog Sticking Head Out Driving Car Window",
     "width": 3454,
     "height": 2303,
     "creator_name": "Christin Lola",
     "creator_id": 204004289,
     "thumbnail_url":
        "https://as1.ftcdn.net/jpg/00/86/76/04/110_F_86760419_NEhOeuriYu82RwfgDqjTeIL9yx7ih5iv.jpg",
     "thumbnail_html_tag":
        "<img src='https://as1.ftcdn.net/jpg/00/86/76/04/110_F_86760419_NEhOeuriYu82RwfgDqjTeIL9yx7ih5iv.jpg'
        alt='German Shepherd Dog Sticking Head Out Driving Car Window'
        title='Photo: German Shepherd Dog Sticking Head Out Driving Car Window' />",
     "thumbnail_width": 110,
     "thumbnail_height": 73,
     "media_type_id": 1,
     "vector_type": null,
     "category": {
       "id": 47,
       "name": "Dogs"
     }
   },
   {
     "id": 84977202,
     "title": "Happy dog playing outside and carrying the American flag",
     "width": 5616,
     "height": 3744,
     "creator_name": "SSilver",
     "creator_id": 200407313,
     "thumbnail_url": "https://as1.ftcdn.net/jpg/00/84/97/72/110_F_84977202_JplQMoMQ5QiZCgVeWLwKhFHCrr4HG99Q.jpg",
     "thumbnail_html_tag":
        "<img src='https://as1.ftcdn.net/jpg/00/84/97/72/110_F_84977202_JplQMoMQ5QiZCgVeWLwKhFHCrr4HG99Q.jpg'
         alt='Happy dog playing outside and carrying the American flag'
         title='Photo: Happy dog playing outside and carrying the American flag' />",
     "thumbnail_width": 110,
     "thumbnail_height": 73,
     "media_type_id": 1,
     "vector_type": null,
     "category": {
       "id": 47,
       "name": "Dogs"
     }
   }
 ]
}

Common search queries

Here are simple examples of common searches.

• Keyword search; assets matching "purple" and "clouds":

  https://stock.adobe.io/Rest/Media/1/Search/Files?search_parameters[words]=purple+clouds&locale=en_US

• Using pagination, get the 3rd page of results (rows 200-300) for the word "dogs":

  https://stock.adobe.io/Rest/Media/1/Search/Files?search_parameters[words]=dogs&search_parameters[limit]=100&search_parameters[offset]=200&locale=en_US

• Search for assets similar in appearance to the specified asset ID:

  https://stock.adobe.io/Rest/Media/1/Search/Files?search_parameters[similar]=121353611&locale=en_US

• Search for assets similar in appearance to the specified URL:

  https://stock.adobe.io/Rest/Media/1/Search/Files?search_parameters[similar_url]=https://i.kinja-img.com/gawker-media/image/upload/xqkbwkexcl7udc5va7pn.jpg&locale=en_US

• Similar asset by URL and keyword:

  https://stock.adobe.io/Rest/Media/1/Search/Files?search_parameters[similar_url]=https://i.kinja-img.com/gawker-media/image/upload/xqkbwkexcl7udc5va7pn.jpg&search_parameters[words]=cats&locale=en_US

• Search for assets depicting the specified model:

  https://stock.adobe.io/Rest/Media/1/Search/Files?search_parameters[model_id]=58344279&locale=en_US

Error codes

Each error generates a JSON array that contains the following keys and values. If your application receives this array and you need assistance, send the array to Adobe.

• An error key.

• Optionally a code key. Specifies an integer designating the category of error. Code values:

  • 10: Invalid access token. The access token that you passed is invalid or expired.
  • 11: Invalid API Key. The API key that you passed is not valid or has expired.
  • 20: Invalid parameters. The URL parameters that you passed are not supported.
  • 31: Invalid Method. The method that you specified does not exist in the method list.
  • 100: Invalid data. Data that you specified as arguments are not supported.

More information

• See the practical search example in Search for assets.
• Refer to the Affiliate API Workflow guide for a complete guide to partnering with Adobe Stock and using the Search API.