Bulk metadata Files API reference

The Files API is used to retrieve metadata from Adobe Stock, either one asset at a time, or in bulk.

<!-- MarkdownTOC --> <!--

Files requests

The Files API returns a JSON-formatted list of metadata attributes for a given list of Stock asset IDs.

Endpoints
Methods
https://stock.adobe.io/Rest/Media/1/Files
GET

Authentication

Optional. The Authorization header is only required for retrieving the is_licensed field.

Request headers

See Headers for Stock API Calls for details about header content.

URL parameters

Parameter
Description
ids
Comma-separated list of file IDs, e.g. ids=100,101. Maximum number of IDs is 110. Exceeding this limit triggers an error. String.
locale
Optional. Location language code for the API to use when returning localized messages. The API can usually get the user's default locale through the Authorization header. This value overrides that or provides a locale if not available through Authorization. String.<br/><br/>Default is en-US. See the full list ofLocales.
result_columns[]
Optional. Fields to include in response. Note that some fields (e.g., is_licensed) require an authorization token. Array[].<br/><br/>✅Tip1: To combine results, use this syntax: result_columns[]=title&result_columns[]=creation_date<br/>✅Tip2: nb_results will return the number of files that exist. Use this to determine if a set of content IDs are still available.<br/><br/>By default, only id is returned.<br/><br/>id :: nb_results :: title :: creator_name :: creator_id :: country_name :: width :: height :: thumbnail_url :: thumbnail_html_tag :: thumbnail_width :: thumbnail_height :: thumbnail_110_url :: thumbnail_110_width :: thumbnail_110_height :: thumbnail_160_url :: thumbnail_160_width :: thumbnail_160_height :: thumbnail_220_url :: thumbnail_220_width :: thumbnail_220_height :: thumbnail_240_url :: thumbnail_240_width :: thumbnail_240_height :: thumbnail_500_url :: thumbnail_500_width :: thumbnail_500_height :: thumbnail_1000_url :: thumbnail_1000_width :: thumbnail_1000_height :: media_type_id :: category :: category_hierarchy :: keywords :: has_releases :: comp_url :: comp_width :: comp_height :: is_licensed :: vector_type :: content_type :: framerate :: duration :: comps :: details_url :: template_type_id :: template_category_ids :: marketing_text :: description :: size_bytes :: premium_level_id :: is_premium :: is_loop :: is_transparent :: licenses :: video_preview_url :: video_preview_width :: video_preview_height :: video_preview_content_length :: video_preview_content_type :: video_small_preview_url :: video_small_preview_width :: video_small_preview_height :: video_small_preview_content_length :: video_small_preview_content_type :: is_gentech :: icon_option

Responses

The response for any given request is dependent on the value of the result_columns argument. As mentioned, the only field returned by default is id (Stock asset ID, integer).

<!-- Start include -->

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

<!-- End include -->

Example requests and responses

The basic use of the API (without setting result columns) only returns the list of IDs without additional metadata.

GET /Rest/Media/1/Files?ids=12345678,57185897,94682947,180905406,175119903,113187776,120451263,117684952,84666330,70910021,89866754,97126353 HTTP/1.1
Host: stock.adobe.io
X-Product: MySampleApp/1.0
x-api-key: MyApiKey

Note that in the response, ID "12345678" does not exist because it is not returned by the API. This is expected behavior. Rather than throw an error for missing assets, it excludes them from the results. This way, the entire request does not fail.

{
    "files": [
        {
            "id": 57185897
        },
        {
            "id": 94682947
        },
        {
            "id": 180905406
        },
        {
            "id": 175119903
        },
        {
            "id": 113187776
        },
        {
            "id": 120451263
        }
    ]
}

This example requests the number of results (nb_results) as well as additional fields.

GET /Rest/Media/1/Files/?ids=77625150,117356939&result_columns[]=nb_results&result_columns[]=id&result_columns[]=thumbnail_url HTTP/1.1
Host: stock.adobe.io
X-Product: MySampleApp/1.0
x-api-key: MyApiKey

{
  "nb_results": 2,
  "files": [
    {
      "id": 77625150,
      "thumbnail_url": "https://as2.ftcdn.net/jpg/00/77/62/51/500_F_77625150_JCiDBzNWtLXnyuXROMgpquQ9NS64OTbY.jpg"
    },
    {
      "id": 117356939,
      "thumbnail_url": "https://as2.ftcdn.net/jpg/01/17/35/69/500_F_117356939_aJF1d2FMSQdrZ2M5m1aY1gjOcXbItMvJ.jpg"
    }
  ]
}

Error handling

If any error is encountered, the response will be a JSON object containing the key error with a textual description of the error and the key code with a numeric identifier for the error.

HTTP Status
JSON Code
JSON Message
400
600
The required X-Product header is missing or invalid
400
601
Authorization required when requesting is_licensed field
400
602
Invalid locale supplied
400
603
Invalid value in result_columns supplied
400
604
Unrecognized query parameter received.
404
605
Unknown id in supplied ids parameter
400
606
More than 110 IDs supplied for ids parameter

Example invalid requests and error responses

curl --header 'X-Api-Key: MyApiKey' 
  https://stock.adobe.io/Rest/Media/1/Files/?ids=100

{"error":"The required X-Product header is missing or invalid","code":"600","case":"ab4a0f466ed85a838853dae159edee6c"}

curl --header 'X-Api-Key: MyApiKey' 
  --header 'X-Product: MySampleApp/1.0' 
  https://stock.adobe.io/Rest/Media/1/Files/?ids=a, 100

{"error":"Required \"ids\" parameter is missing or invalid","code":"605","case":"01f49fa990a7579aa69b6fd232504c71"}