@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Shutterstock API Explorer
@base https://api.shutterstock.com
@version 1.2.0
@auth Bearer basic | OAuth2
@endpoints 109
@hint download_for_search
@toc images(20), bulk_search(1), videos(18), audio(17), sfx(6), editorial(24), cv(4), catalog(7), contributors(5), user(3), test(2), oauth(2)

@group images
@endpoint GET /v2/images/search
@optional {library: [str]=shutterstock, added_date: str(date), added_date_start: str(date), aspect_ratio_min: num, aspect_ratio_max: num, aspect_ratio: num, added_date_end: str(date), category: str, color: str, contributor: [str], contributor_country: any, fields: str, height: int, height_from: int, height_to: int, image_type: [str], keyword_safe_search: bool=true, language: str(ar/bg/bn/cs/da/de/el/en/es/fi/fr/gu/he/hi/hr/hu/id/it/ja/kn/ko/ml/mr/nb/nl/or/pl/pt/ro/ru/sk/sl/sv/ta/te/th/tr/uk/ur/vi/zh/zh-Hant), license: [str], model: [str], orientation: str(horizontal/vertical), page: int=1, per_page: int=20, people_model_released: bool, people_age: str(infants/children/teenagers/20s/30s/40s/50s/60s/older), people_ethnicity: [str], people_gender: str(male/female/both), people_number: int, query: str, region: any, safe: bool=true, sort: str(newest/popular/relevance/random)=popular, spellcheck_query: bool=true, view: str(minimal/full)=minimal, width: int, width_from: int, width_to: int}
@returns(200) {data: [map], message: str, page: int, per_page: int, search_id: str, spellcheck_info: map, total_count: int}
@errors {400, 401, 403}

@endgroup

@group bulk_search
@endpoint POST /v2/bulk_search/images
@optional {added_date: str(date), added_date_start: str(date), aspect_ratio_min: num, aspect_ratio_max: num, aspect_ratio: num, added_date_end: str(date), category: str, color: str, contributor: [str], contributor_country: any, fields: str, height: int, height_from: int, height_to: int, image_type: [str], keyword_safe_search: bool=true, language: str(ar/bg/bn/cs/da/de/el/en/es/fi/fr/gu/he/hi/hr/hu/id/it/ja/kn/ko/ml/mr/nb/nl/or/pl/pt/ro/ru/sk/sl/sv/ta/te/th/tr/uk/ur/vi/zh/zh-Hant), license: [str], model: [str], orientation: str(horizontal/vertical), page: int=1, per_page: int=20, people_model_released: bool, people_age: str(infants/children/teenagers/20s/30s/40s/50s/60s/older), people_ethnicity: [str], people_gender: str(male/female/both), people_number: int, region: any, safe: bool=true, sort: str(newest/popular/relevance/random)=popular, spellcheck_query: bool=true, view: str(minimal/full)=minimal, width: int, width_from: int, width_to: int}
@returns(200) {results: [map], bulk_search_id: str}
@errors {400, 401, 403}

@endgroup

@group images
@endpoint GET /v2/images/search/suggestions
@required {query: str}
@optional {limit: int=10}
@returns(200) {data: [str]}
@errors {400, 401, 403}

@endpoint POST /v2/images/search/suggestions
@required {text: str}
@returns(200) {keywords: [str]}
@errors {400, 401, 403}

@endpoint GET /v2/images
@required {id: [str(asset-id)]}
@optional {view: str(minimal/full)=minimal, search_id: str}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint GET /v2/images/{id}
@required {id: str(asset-id)}
@optional {language: str(ar/bg/bn/cs/da/de/el/en/es/fi/fr/gu/he/hi/hr/hu/id/it/ja/kn/ko/ml/mr/nb/nl/or/pl/pt/ro/ru/sk/sl/sv/ta/te/th/tr/uk/ur/vi/zh/zh-Hant), view: str(minimal/full)=full, search_id: str}
@returns(200) {added_date: str(date), affiliate_url: str(uri), aspect: num, assets: map{huge_jpg: map{display_name: str, dpi: int, file_size: int, format: str, height: int, is_licensable: bool, width: int}, huge_thumb: map{height: int, url: str, width: int}, large_thumb: map{height: int, url: str, width: int}, medium_jpg: map{display_name: str, dpi: int, file_size: int, format: str, height: int, is_licensable: bool, width: int}, preview: map{height: int, url: str, width: int}, preview_1000: map{height: int, url: str, width: int}, preview_1500: map{height: int, url: str, width: int}, small_jpg: map{display_name: str, dpi: int, file_size: int, format: str, height: int, is_licensable: bool, width: int}, small_thumb: map{height: int, url: str, width: int}, supersize_jpg: map{display_name: str, dpi: int, file_size: int, format: str, height: int, is_licensable: bool, width: int}, vector_eps: map{display_name: str, dpi: int, file_size: int, format: str, height: int, is_licensable: bool, width: int}, mosaic: map{height: int, url: str, width: int}}, categories: [map], contributor: map{id: str}, description: str, has_model_release: bool, has_property_release: bool, id: str, image_type: str, is_adult: bool, is_editorial: bool, is_illustration: bool, keywords: [str], media_type: str, model_releases: [map], models: [map], releases: [str], url: str}
@errors {400, 401, 403}

@endpoint GET /v2/images/categories
@optional {language: str(ar/bg/bn/cs/da/de/el/en/es/fi/fr/gu/he/hi/hr/hu/id/it/ja/kn/ko/ml/mr/nb/nl/or/pl/pt/ro/ru/sk/sl/sv/ta/te/th/tr/uk/ur/vi/zh/zh-Hant)}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint GET /v2/images/{id}/similar
@required {id: str}
@optional {language: str(ar/bg/bn/cs/da/de/el/en/es/fi/fr/gu/he/hi/hr/hu/id/it/ja/kn/ko/ml/mr/nb/nl/or/pl/pt/ro/ru/sk/sl/sv/ta/te/th/tr/uk/ur/vi/zh/zh-Hant), page: int=1, per_page: int=20, view: str(minimal/full)=minimal}
@returns(200) {data: [map], message: str, page: int, per_page: int, search_id: str, spellcheck_info: map, total_count: int}
@errors {400, 401, 403}

@endpoint POST /v2/images/licenses
@required {images: [any]}
@optional {subscription_id: str, format: str(eps/jpg), size: str(small/medium/huge/vector/custom)=huge, search_id: str}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint GET /v2/images/licenses
@optional {image_id: str, license: str, page: int=1, per_page: int=20, sort: str(newest/oldest)=newest, username: str, start_date: str(date-time), end_date: str(date-time), download_availability: str(all/downloadable/non_downloadable)=all, team_history: bool=false}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint POST /v2/images/licenses/{id}/downloads
@required {id: str}
@optional {auth_cookie: map{name!: str, value!: str}, show_modal: bool, size: str(small/medium/huge/supersize/vector), verification_code: str}
@returns(200) {url: str}
@errors {400, 401, 403}

@endpoint GET /v2/images/recommendations
@required {id: [str]}
@optional {max_items: int=20, safe: bool=true}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint POST /v2/images/collections
@required {name: str}
@returns(201) {id: str}
@errors {400, 401, 403}

@endpoint GET /v2/images/collections
@optional {embed: [str], page: int=1, per_page: int=100}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint GET /v2/images/collections/{id}
@required {id: str}
@optional {embed: [str], share_code: str}
@returns(200) {cover_item: map{added_time: str(date-time), id: str, media_type: str}, created_time: str(date-time), id: str, items_updated_time: str(date-time), name: str, share_code: str, share_url: str, total_item_count: int, updated_time: str(date-time)}
@errors {400, 401, 403, 404}

@endpoint POST /v2/images/collections/{id}
@required {id: str, name: str}
@returns(204)
@errors {400, 401, 403, 404}

@endpoint DELETE /v2/images/collections/{id}
@required {id: str}
@returns(204)
@errors {400, 401, 403, 404}

@endpoint POST /v2/images/collections/{id}/items
@required {id: str, items: [map{added_time: str(date-time), id!: str, media_type: str}]}
@returns(204)
@errors {400, 401, 403, 404}

@endpoint GET /v2/images/collections/{id}/items
@required {id: str}
@optional {page: int=1, per_page: int=100, share_code: str, sort: str(newest/oldest)=oldest}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403, 404}

@endpoint DELETE /v2/images/collections/{id}/items
@required {id: str}
@optional {item_id: [str]}
@returns(204)
@errors {400, 401, 403, 404}

@endpoint GET /v2/images/updated
@optional {type: [str], start_date: str(date-or-date-time), end_date: str(date-or-date-time), interval: str=1 HOUR, page: int=1, per_page: int=100, sort: str(newest/oldest)=newest}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}

@endgroup

@group videos
@endpoint GET /v2/videos/search
@optional {added_date: str(date), added_date_start: str(date), added_date_end: str(date), aspect_ratio: str(4_3/16_9/nonstandard), category: str, contributor: [str], contributor_country: [str(country-code-2)], duration: int, duration_from: int, duration_to: int, fps: num, fps_from: num, fps_to: num, keyword_safe_search: bool=true, language: str(ar/bg/bn/cs/da/de/el/en/es/fi/fr/gu/he/hi/hr/hu/id/it/ja/kn/ko/ml/mr/nb/nl/or/pl/pt/ro/ru/sk/sl/sv/ta/te/th/tr/uk/ur/vi/zh/zh-Hant), license: [str], model: [str], orientation: str(vertical/horizontal), page: int=1, per_page: int=20, people_age: str(infants/children/teenagers/20s/30s/40s/50s/60s/older), people_ethnicity: [str], people_gender: str(male/female/both), people_number: int, people_model_released: bool, query: str, resolution: str(4k/standard_definition/high_definition), safe: bool=true, sort: str(newest/popular/relevance/random)=popular, view: str(minimal/full)=minimal}
@returns(200) {data: [map], message: str, page: int, per_page: int, total_count: int, search_id: str}
@errors {400, 401, 403, 404}

@endpoint GET /v2/videos/search/suggestions
@required {query: str}
@optional {limit: int=10}
@returns(200) {data: [str]}
@errors {400, 401, 403}

@endpoint GET /v2/videos
@required {id: [str(asset-id)]}
@optional {view: str(minimal/full)=minimal, search_id: str}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint GET /v2/videos/{id}
@required {id: str(asset-id)}
@optional {language: str(ar/bg/bn/cs/da/de/el/en/es/fi/fr/gu/he/hi/hr/hu/id/it/ja/kn/ko/ml/mr/nb/nl/or/pl/pt/ro/ru/sk/sl/sv/ta/te/th/tr/uk/ur/vi/zh/zh-Hant), view: str(minimal/full)=full, search_id: str}
@returns(200) {added_date: str(date), affiliate_url: str(uri), aspect: num, aspect_ratio: str, assets: map{4k: map{display_name: str, file_size: int, format: str, fps: num, height: int, is_licensable: bool, width: int}, hd: map{display_name: str, file_size: int, format: str, fps: num, height: int, is_licensable: bool, width: int}, preview_jpg: map{url: str}, preview_mp4: map{url: str}, preview_webm: map{url: str}, sd: map{display_name: str, file_size: int, format: str, fps: num, height: int, is_licensable: bool, width: int}, thumb_jpg: map{url: str}, thumb_jpgs: map{urls: [str]}, thumb_mp4: map{url: str}, thumb_webm: map{url: str}, web: map{display_name: str, file_size: int, format: str, fps: num, height: int, is_licensable: bool, width: int}}, categories: [map], contributor: map{id: str}, description: str, duration: num, has_model_release: bool, has_property_release: bool, id: str, is_adult: bool, is_editorial: bool, is_select: bool, keywords: [str], media_type: str, models: [map], releases: [map], url: str}
@errors {400, 401, 403, 404}

@endpoint POST /v2/videos/licenses
@required {videos: [map{auth_cookie: map, editorial_acknowledgement: bool, metadata: map, price: num, search_id: str, show_modal: bool, size: str, subscription_id: str, video_id!: str}]}
@optional {subscription_id: str, size: str(web/sd/hd/4k)=web, search_id: str}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint GET /v2/videos/licenses
@optional {video_id: str, license: str, page: int=1, per_page: int=20, sort: str(newest/oldest)=newest, username: str, start_date: str(date-time), end_date: str(date-time), download_availability: str(all/downloadable/non_downloadable)=all, team_history: bool=false}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint POST /v2/videos/licenses/{id}/downloads
@required {id: str}
@optional {auth_cookie: map{name!: str, value!: str}, show_modal: bool, size: str(web/sd/hd/4k), verification_code: str}
@returns(200) {url: str}
@errors {400, 401, 403}

@endpoint POST /v2/videos/collections
@required {name: str}
@returns(201) {id: str}
@errors {400, 401, 403}

@endpoint GET /v2/videos/collections
@optional {page: int=1, per_page: int=100, embed: [str]}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint GET /v2/videos/collections/{id}
@required {id: str}
@optional {embed: [str], share_code: str}
@returns(200) {cover_item: map{added_time: str(date-time), id: str, media_type: str}, created_time: str(date-time), id: str, items_updated_time: str(date-time), name: str, share_code: str, share_url: str, total_item_count: int, updated_time: str(date-time)}
@errors {400, 401, 403, 404}

@endpoint POST /v2/videos/collections/{id}
@required {id: str, name: str}
@returns(204)
@errors {400, 401, 403, 404}

@endpoint DELETE /v2/videos/collections/{id}
@required {id: str}
@returns(204)
@errors {400, 401, 403, 404}

@endpoint GET /v2/videos/categories
@optional {language: str(ar/bg/bn/cs/da/de/el/en/es/fi/fr/gu/he/hi/hr/hu/id/it/ja/kn/ko/ml/mr/nb/nl/or/pl/pt/ro/ru/sk/sl/sv/ta/te/th/tr/uk/ur/vi/zh/zh-Hant)}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint POST /v2/videos/collections/{id}/items
@required {id: str, items: [map{added_time: str(date-time), id!: str, media_type: str}]}
@returns(204)
@errors {400, 401, 403, 404}

@endpoint GET /v2/videos/collections/{id}/items
@required {id: str}
@optional {page: int=1, per_page: int=100, share_code: str, sort: str(newest/oldest)=oldest}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403, 404}

@endpoint DELETE /v2/videos/collections/{id}/items
@required {id: str}
@optional {item_id: [str]}
@returns(204)
@errors {400, 401, 403, 404}

@endpoint GET /v2/videos/{id}/similar
@required {id: str(asset-id)}
@optional {language: str(ar/bg/bn/cs/da/de/el/en/es/fi/fr/gu/he/hi/hr/hu/id/it/ja/kn/ko/ml/mr/nb/nl/or/pl/pt/ro/ru/sk/sl/sv/ta/te/th/tr/uk/ur/vi/zh/zh-Hant), page: int=1, per_page: int=20, view: str(minimal/full)=minimal}
@returns(200) {data: [map], message: str, page: int, per_page: int, total_count: int, search_id: str}
@errors {400, 401, 403}

@endpoint GET /v2/videos/updated
@optional {start_date: str(date-or-date-time), end_date: str(date-or-date-time), interval: str=1 HOUR, page: int=1, per_page: int=100, sort: str(newest/oldest)=newest}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}

@endgroup

@group audio
@endpoint GET /v2/audio/search
@optional {artists: [str], bpm: int, bpm_from: int, bpm_to: int, duration: int, duration_from: int, duration_to: int, genre: [str], is_instrumental: bool, instruments: [str], moods: [str], page: int=1, per_page: int=20, query: str, sort: str(score/ranking_all/artist/title/bpm/freshness/duration), sort_order: str(asc/desc)=desc, vocal_description: str, view: str(minimal/full)=minimal, fields: str, library: str(shutterstock/premier)=premier, language: str}
@returns(200) {data: [map], message: str, page: int, per_page: int, total_count: int, search_id: str}
@errors {400, 401, 403}

@endpoint GET /v2/audio/genres
@optional {language: str}
@returns(200) {data: [str]}

@endpoint GET /v2/audio/instruments
@optional {language: str}
@returns(200) {data: [str]}

@endpoint GET /v2/audio/moods
@optional {language: str}
@returns(200) {data: [str]}

@endpoint GET /v2/audio
@required {id: [str]}
@optional {view: str(minimal/full)=minimal, search_id: str}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint GET /v2/audio/{id}
@required {id: int}
@optional {view: str(minimal/full)=full, search_id: str}
@returns(200) {added_date: str(date), affiliate_url: str, album: map{id: str, title: str}, artists: [map], assets: map{album_art: map{file_size: int, url: str}, clean_audio: map{file_size: int, url: str}, original_audio: map{file_size: int, url: str}, preview_mp3: map{file_size: int, url: str}, preview_ogg: map{file_size: int, url: str}, waveform: map{file_size: int, url: str}, shorts_loops_stems: map{shorts: any, loops: any, stems: any}}, bpm: int, contributor: map{id: str}, deleted_time: str(date-time), description: str, duration: num, genres: [str], id: str, instruments: [str], is_adult: bool, is_instrumental: bool, isrc: str, keywords: [str], language: str, lyrics: str, media_type: str, model_releases: [map], moods: [str], published_time: str(date-time), recording_version: str, releases: [str], similar_artists: [map], submitted_time: str(date-time), title: str, updated_time: str(date-time), vocal_description: str, url: str}
@errors {400, 401, 403}

@endpoint POST /v2/audio/licenses
@required {audio: [map{audio_id!: str, license: str, search_id: str}]}
@optional {license: str(audio_platform/premier_music_basic/premier_music_extended/premier_music_pro/premier_music_comp/asset_all_music), search_id: str}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint GET /v2/audio/licenses
@optional {audio_id: str, license: str, page: int=1, per_page: int=20, sort: str(newest/oldest)=newest, username: str, start_date: str(date-time), end_date: str(date-time), download_availability: str(all/downloadable/non_downloadable)=all, team_history: bool=false}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint POST /v2/audio/licenses/{id}/downloads
@required {id: str}
@returns(200) {url: str, shorts_loops_stems: str}
@errors {400, 401, 403}

@endpoint POST /v2/audio/collections
@required {name: str}
@returns(201) {id: str}
@errors {400, 401, 403}

@endpoint GET /v2/audio/collections
@optional {page: int=1, per_page: int=100, embed: [str]}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint GET /v2/audio/collections/{id}
@required {id: str}
@optional {embed: [str], share_code: str}
@returns(200) {cover_item: map{added_time: str(date-time), id: str, media_type: str}, created_time: str(date-time), id: str, items_updated_time: str(date-time), name: str, share_code: str, share_url: str, total_item_count: int, updated_time: str(date-time)}
@errors {400, 401, 403, 404}

@endpoint POST /v2/audio/collections/{id}
@required {id: str, name: str}
@returns(204)
@errors {400, 401, 403, 404}

@endpoint DELETE /v2/audio/collections/{id}
@required {id: str}
@returns(204)
@errors {400, 401, 403, 404}

@endpoint POST /v2/audio/collections/{id}/items
@required {id: str, items: [map{added_time: str(date-time), id!: str, media_type: str}]}
@returns(204)
@errors {400, 401, 403, 404}

@endpoint GET /v2/audio/collections/{id}/items
@required {id: str}
@optional {page: int=1, per_page: int=100, share_code: str, sort: str(newest/oldest)=oldest}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403, 404}

@endpoint DELETE /v2/audio/collections/{id}/items
@required {id: str}
@optional {item_id: [str]}
@returns(204)
@errors {400, 401, 403, 404}

@endgroup

@group sfx
@endpoint GET /v2/sfx/search
@optional {added_date: str(date), added_date_start: str(date), added_date_end: str(date), duration: int, duration_from: int, duration_to: int, page: int=1, per_page: int=20, query: str, safe: bool=true, sort: str(popular/newest/relevance/random/oldest)=popular, view: str(minimal/full)=minimal, language: str(ar/bg/bn/cs/da/de/el/en/es/fi/fr/gu/he/hi/hr/hu/id/it/ja/kn/ko/ml/mr/nb/nl/or/pl/pt/ro/ru/sk/sl/sv/ta/te/th/tr/uk/ur/vi/zh/zh-Hant)}
@returns(200) {data: [map], message: str, page: int, per_page: int, total_count: int, search_id: str}
@errors {400, 401, 403, 503}

@endpoint GET /v2/sfx/{id}
@required {id: int}
@optional {language: str(ar/bg/bn/cs/da/de/el/en/es/fi/fr/gu/he/hi/hr/hu/id/it/ja/kn/ko/ml/mr/nb/nl/or/pl/pt/ro/ru/sk/sl/sv/ta/te/th/tr/uk/ur/vi/zh/zh-Hant), view: str(minimal/full)=minimal, library: str(shutterstock/premier/premiumbeat), search_id: str}
@returns(200) {added_date: str(date), affiliate_url: str, artist: str, assets: map{preview_mp3: map{file_size: int, url: str}, waveform: map{file_size: int, url: str}}, contributor: map{id: str}, description: str, duration: num, id: str, keywords: [str], media_type: str, releases: [str], title: str, updated_time: str(date-time), url: str}
@errors {400, 401, 403, 503}

@endpoint GET /v2/sfx
@required {id: [str(asset-id)]}
@optional {view: str(minimal/full)=minimal, language: str(ar/bg/bn/cs/da/de/el/en/es/fi/fr/gu/he/hi/hr/hu/id/it/ja/kn/ko/ml/mr/nb/nl/or/pl/pt/ro/ru/sk/sl/sv/ta/te/th/tr/uk/ur/vi/zh/zh-Hant), library: str(shutterstock/premier/premiumbeat), search_id: str}
@returns(200) {data: [map]}
@errors {400, 401, 403}

@endpoint GET /v2/sfx/licenses
@optional {sfx_id: str, license: str, page: int=1, per_page: int=20, sort: str(newest/oldest)=newest, username: str, start_date: str(date-time), end_date: str(date-time), license_id: str, download_availability: str(all/downloadable/non_downloadable)=all, team_history: bool=false}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint POST /v2/sfx/licenses
@required {sound_effects: [map{sfx_id!: str, audio_layout: str, format: str, search_id: str, subscription_id!: str}]}
@returns(200) {data: [map], errors: [map], message: str}
@errors {400, 401, 403}

@endpoint POST /v2/sfx/licenses/{id}/downloads
@required {id: str}
@returns(200) {url: str}
@errors {400, 401, 403}

@endgroup

@group editorial
@endpoint GET /v2/editorial/images/search
@required {country: str(country-code-3)}
@optional {query: str, sort: str(relevant/newest/oldest)=relevant, category: str, supplier_code: [str], date_start: str(date), date_end: str(date), per_page: int=20, cursor: str}
@returns(200) {data: [map], message: str, next: str, page: int, per_page: int, prev: str, search_id: str, total_count: int}
@errors {400, 401, 403, 406}

@endpoint GET /v2/editorial/images/categories
@returns(200) {data: [map]}
@errors {400, 401, 403}

@endpoint GET /v2/editorial/images/updated
@required {type: str(edit/addition), date_updated_start: str(date-time), date_updated_end: str(date-time), country: str(country-code-3)}
@optional {date_taken_start: str(date), date_taken_end: str(date), cursor: str, sort: str(newest/oldest)=newest, supplier_code: [str], per_page: int=500}
@returns(200) {data: [map], message: str, next: str, per_page: int, prev: str}
@errors {400, 401, 403, 406}

@endpoint GET /v2/editorial/images/{id}
@required {id: str, country: str(country-code-3)}
@returns(200) {aspect: num, assets: map{original: map{display_name: str, dpi: int, file_size: int, format: str, height: int, is_licensable: bool, width: int}, thumb_170: map{height: int, url: str, width: int}, thumb_220: map{height: int, url: str, width: int}, watermark_450: map{height: int, url: str, width: int}, watermark_1500: map{height: int, url: str, width: int}, small_jpg: map{display_name: str, dpi: int, file_size: int, format: str, height: int, is_licensable: bool, width: int}, medium_jpg: map{display_name: str, dpi: int, file_size: int, format: str, height: int, is_licensable: bool, width: int}}, byline: str, caption: str, categories: [map], date_taken: str(date), description: str, id: str, keywords: [str], special_instructions: str, title: str}
@errors {400, 401, 403, 404}

@endpoint GET /v2/editorial/images
@required {id: [str], country: str(country-code-3)}
@optional {search_id: str}
@returns(200) {data: [map], search_id: str, total_count: int}
@errors {400, 401, 403}

@endpoint GET /v2/editorial/images/licenses
@optional {image_id: str, license: str, page: int=1, per_page: int=20, sort: str(newest/oldest)=newest, username: str, start_date: str(date-time), end_date: str(date-time), download_availability: str(all/downloadable/non_downloadable)=all, team_history: bool=false}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint POST /v2/editorial/images/licenses
@required {country: any, editorial: [map{editorial_id!: str, license!: str, metadata: map, size: str}]}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403, 406}

@endpoint GET /v2/editorial/images/livefeeds
@required {country: str(country-code-3)}
@optional {page: int=1, per_page: int=20}
@returns(200) {data: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403, 404}

@endpoint GET /v2/editorial/images/livefeeds/{id}
@required {id: str, country: str(country-code-3)}
@returns(200) {cover_item: map{height: int, id: str, url: str, width: int}, created_time: str(date-time), id: str, name: str, total_item_count: int}
@errors {400, 401, 403, 404}

@endpoint GET /v2/editorial/images/livefeeds/{id}/items
@required {id: str, country: str(country-code-3)}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403, 404}

@endpoint GET /v2/editorial/videos/search
@required {country: str(country-code-3)}
@optional {query: str, sort: str(relevant/newest/oldest)=relevant, category: str, supplier_code: [str], date_start: str(date), date_end: str(date), resolution: str(4k/high_definition/standard_definition), fps: num, per_page: int=20, cursor: str}
@returns(200) {data: [map], message: str, next: str, page: int, per_page: int, prev: str, search_id: str, total_count: int}
@errors {400, 401, 403, 406}

@endpoint GET /v2/editorial/videos/categories
@returns(200) {data: [map]}
@errors {400, 401, 403}

@endpoint GET /v2/editorial/videos/{id}
@required {id: str, country: str(country-code-3)}
@optional {search_id: str}
@returns(200) {aspect: num, assets: map{original: map{display_name: str, file_size: int, format: str, fps: num, height: int, is_licensable: bool, width: int}, preview_mp4: map{url: str}, preview_webm: map{url: str}, thumb_jpg: map{url: str}}, byline: str, caption: str, categories: [map], date_taken: str(date), description: str, id: str, keywords: [str], title: str}
@errors {400, 401, 403, 406}

@endpoint GET /v2/editorial/videos
@required {id: [str], country: str(country-code-3)}
@optional {search_id: str}
@returns(200) {data: [map], search_id: str, total_count: int}
@errors {400, 401, 403}

@endpoint GET /v2/editorial/videos/licenses
@optional {video_id: str, license: str, page: int=1, per_page: int=20, sort: str(newest/oldest)=newest, username: str, start_date: str(date-time), end_date: str(date-time), download_availability: str(all/downloadable/non_downloadable)=all, team_history: bool=false}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint POST /v2/editorial/videos/licenses
@required {country: any, editorial: [map{editorial_id!: str, license!: str, metadata: map, size: str}]}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endgroup

@group cv
@endpoint POST /v2/cv/images
@required {base64_image: str}
@returns(201) {upload_id: str}
@errors {400, 401, 403, 413, 415}

@endpoint GET /v2/cv/similar/images
@required {asset_id: str}
@optional {license: [str]=commercial, safe: bool=true, language: str(ar/bg/bn/cs/da/de/el/en/es/fi/fr/gu/he/hi/hr/hu/id/it/ja/kn/ko/ml/mr/nb/nl/or/pl/pt/ro/ru/sk/sl/sv/ta/te/th/tr/uk/ur/vi/zh/zh-Hant), page: int=1, per_page: int=20, view: str(minimal/full)=minimal}
@returns(200) {data: [map], message: str, page: int, per_page: int, search_id: str, spellcheck_info: map, total_count: int}
@errors {400, 401, 403}

@endpoint GET /v2/cv/similar/videos
@required {asset_id: str}
@optional {license: [str]=commercial, safe: bool=true, language: str(ar/bg/bn/cs/da/de/el/en/es/fi/fr/gu/he/hi/hr/hu/id/it/ja/kn/ko/ml/mr/nb/nl/or/pl/pt/ro/ru/sk/sl/sv/ta/te/th/tr/uk/ur/vi/zh/zh-Hant), page: int=1, per_page: int=20, view: str(minimal/full)=minimal}
@returns(200) {data: [map], message: str, page: int, per_page: int, total_count: int, search_id: str}
@errors {400, 401, 403}

@endpoint GET /v2/cv/keywords
@required {asset_id: any}
@returns(200) {data: [str], errors: [map], message: str}
@errors {400, 401, 403, 415}

@endgroup

@group catalog
@endpoint GET /v2/catalog/search
@optional {sort: str(newest/oldest)=newest, page: int=1, per_page: int=20, query: str, collection_id: [str], asset_type: [str]}
@returns(200) {page: num, per_page: num, total_count: num, data: [map]}
@errors {400, 401, 403}

@endpoint GET /v2/catalog/collections
@optional {page: int=1, per_page: int=20, sort: str(newest/oldest)=newest, shared: bool=false}
@returns(200) {page: num, per_page: num, total_count: num, data: [map]}
@errors {400}

@endpoint POST /v2/catalog/collections
@required {name: str}
@optional {visibility: str(private/public)=private, items: [map{asset!: map}]}
@returns(201) {id: str, name: str, cover_asset: map{id: str, asset: map{id: str, type: str, name: str}, created_time: str(date-time), collection_ids: [str]}, total_item_count: num, created_time: str(date-time), updated_time: str(date-time), visibility: str, role_assignments: map{collection_id: str, roles: map{owners: [map], editors: [map], viewers: [map]}}}

@endpoint PATCH /v2/catalog/collections/{collection_id}
@required {collection_id: str}
@optional {name: str, visibility: str(private/public), cover_asset: map{id!: str}}
@returns(200) {id: str, name: str, cover_asset: map{id: str, asset: map{id: str, type: str, name: str}, created_time: str(date-time), collection_ids: [str]}, total_item_count: num, created_time: str(date-time), updated_time: str(date-time), visibility: str, role_assignments: map{collection_id: str, roles: map{owners: [map], editors: [map], viewers: [map]}}}

@endpoint DELETE /v2/catalog/collections/{collection_id}
@required {collection_id: str}
@returns(204)
@errors {404}

@endpoint POST /v2/catalog/collections/{collection_id}/items
@required {collection_id: str, items: [map{asset!: map}]}
@returns(200) {id: str, name: str, cover_asset: map{id: str, asset: map{id: str, type: str, name: str}, created_time: str(date-time), collection_ids: [str]}, total_item_count: num, created_time: str(date-time), updated_time: str(date-time), visibility: str, role_assignments: map{collection_id: str, roles: map{owners: [map], editors: [map], viewers: [map]}}}

@endpoint DELETE /v2/catalog/collections/{collection_id}/items
@required {collection_id: str, items: [map{id!: str}]}
@returns(200) {id: str, name: str, cover_asset: map{id: str, asset: map{id: str, type: str, name: str}, created_time: str(date-time), collection_ids: [str]}, total_item_count: num, created_time: str(date-time), updated_time: str(date-time), visibility: str, role_assignments: map{collection_id: str, roles: map{owners: [map], editors: [map], viewers: [map]}}}

@endgroup

@group contributors
@endpoint GET /v2/contributors
@required {id: [str]}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endpoint GET /v2/contributors/{contributor_id}
@required {contributor_id: str}
@returns(200) {about: str, contributor_type: [str], display_name: str, equipment: [str], id: str, location: str, portfolio_url: str, social_media: map{facebook: str, google_plus: str, linkedin: str, pinterest: str, tumblr: str, twitter: str}, styles: [str], subjects: [str], website: str}
@errors {400, 401, 403}

@endpoint GET /v2/contributors/{contributor_id}/collections
@required {contributor_id: str}
@optional {sort: str(newest/last_updated/item_count)}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403, 404}

@endpoint GET /v2/contributors/{contributor_id}/collections/{id}
@required {contributor_id: str, id: str}
@returns(200) {cover_item: map{added_time: str(date-time), id: str, media_type: str}, created_time: str(date-time), id: str, items_updated_time: str(date-time), name: str, share_code: str, share_url: str, total_item_count: int, updated_time: str(date-time)}
@errors {400, 401, 403, 404}

@endpoint GET /v2/contributors/{contributor_id}/collections/{id}/items
@required {contributor_id: str, id: str}
@optional {page: int=1, per_page: int=20, sort: str(newest/oldest)}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403, 404}

@endgroup

@group user
@endpoint GET /v2/user
@returns(200) {contributor_id: str, customer_id: str, email: str, first_name: str, full_name: str, id: str, is_premier: bool, is_premier_parent: bool, language: str, last_name: str, only_enhanced_license: bool, only_sensitive_use: bool, organization_id: str, premier_permissions: [str], username: str}
@errors {400, 401, 403}

@endpoint GET /v2/user/access_token
@returns(200) {client_id: str, contributor_id: str, customer_id: str, expires_in: int, organization_id: str, realm: str, scopes: [str], user_id: str, username: str}
@errors {400, 401, 403}

@endpoint GET /v2/user/subscriptions
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403}

@endgroup

@group test
@endpoint GET /v2/test
@optional {text: str=ok}
@returns(200) {text: str}
@errors {400, 401, 403}

@endpoint GET /v2/test/validate
@required {id: int}
@optional {tag: [str], user-agent: str}
@returns(200) {header: map{user-agent: str}, query: map{id: int, tag: [str]}}
@errors {400, 401, 403}

@endgroup

@group oauth
@endpoint GET /v2/oauth/authorize
@required {client_id: str, redirect_uri: str, response_type: str, state: str}
@optional {realm: str(customer/contributor)=customer, scope: str=user.view}
@errors {302, 400, 401, 403}

@endpoint POST /v2/oauth/access_token
@required {client_id: str, grant_type: str(authorization_code/client_credentials/refresh_token)}
@optional {client_secret: str, code: str, realm: str(customer/contributor)=customer, expires: bool=false, refresh_token: str}
@returns(200) {access_token: str, expires_in: int, token_type: str, refresh_token: str, user_token: str}
@errors {400, 401, 403}

@endgroup

@group editorial
@endpoint GET /v2/editorial/{id}
@required {id: str, country: str(country-code-3)}
@optional {search_id: str}
@returns(200) {aspect: num, assets: map{original: map{display_name: str, dpi: int, file_size: int, format: str, height: int, is_licensable: bool, width: int}, thumb_170: map{height: int, url: str, width: int}, thumb_220: map{height: int, url: str, width: int}, watermark_450: map{height: int, url: str, width: int}, watermark_1500: map{height: int, url: str, width: int}, small_jpg: map{display_name: str, dpi: int, file_size: int, format: str, height: int, is_licensable: bool, width: int}, medium_jpg: map{display_name: str, dpi: int, file_size: int, format: str, height: int, is_licensable: bool, width: int}}, byline: str, caption: str, categories: [map], date_taken: str(date), description: str, id: str, keywords: [str], special_instructions: str, title: str}
@errors {400, 401, 403, 404}

@endpoint POST /v2/editorial/licenses
@required {country: any, editorial: [map{editorial_id!: str, license!: str, metadata: map, size: str}]}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403, 406}

@endpoint GET /v2/editorial/livefeeds
@required {country: str(country-code-3)}
@optional {page: int=1, per_page: int=20}
@returns(200) {data: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403, 406}

@endpoint GET /v2/editorial/livefeeds/{id}
@required {id: str, country: str(country-code-3)}
@returns(200) {cover_item: map{height: int, id: str, url: str, width: int}, created_time: str(date-time), id: str, name: str, total_item_count: int}
@errors {400, 401, 403, 406}

@endpoint GET /v2/editorial/livefeeds/{id}/items
@required {id: str, country: str(country-code-3)}
@returns(200) {data: [map], errors: [map], message: str, page: int, per_page: int, total_count: int}
@errors {400, 401, 403, 406}

@endpoint GET /v2/editorial/search
@required {country: str(country-code-3)}
@optional {query: str, sort: str(relevant/newest/oldest)=relevant, category: str, supplier_code: [str], date_start: str(date), date_end: str(date), per_page: int=20, cursor: str}
@returns(200) {data: [map], message: str, next: str, page: int, per_page: int, prev: str, search_id: str, total_count: int}
@errors {400, 401, 403, 406}

@endpoint GET /v2/editorial/categories
@returns(200) {data: [map]}
@errors {400, 401, 403}

@endpoint GET /v2/editorial/updated
@required {type: str(edit/addition), date_updated_start: str(date-time), date_updated_end: str(date-time), country: str(country-code-3)}
@optional {date_taken_start: str(date), date_taken_end: str(date), cursor: str, sort: str(newest/oldest)=newest, supplier_code: [str], per_page: int=500}
@returns(200) {data: [map], message: str, next: str, per_page: int, prev: str}
@errors {400, 401, 403, 406}

@endgroup

@end