openapi: 3.0.0 info: description: >- This is the Alamy API. It allows for searching and fetching of images and their associated metadata from the Alamy archive. version: 1.0.0 title: Alamy API contact: name: Alamy Customer Services url: https://www.alamy.com/api-partnerships/ email: customerserviceall@alamy.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.alamy.com/v3 tags: - name: Authentication description: Authenticating to the API - name: Download description: Download a media item - name: Feed description: A list of newly added or modified content meeting the provided criteria - name: Item description: Retrieve metadata for one or more media items - name: Orders description: Retrieve user order history - name: Search description: Search for media items paths: /search: get: tags: - Search security: - OAuth2: - search summary: Search for media items description: Search for media items across the Alamy platform operationId: search parameters: - name: q in: query required: true description: The search query to conduct across the archive schema: type: string example: 'motogp' - name: offset in: query required: false description: The offset within the results to start from schema: type: integer example: 10 default: 0 - name: limit in: query required: false description: The maximum number of items to return per page capped to 100 schema: type: integer example: 10 default: 100 - name: library in: query required: false description: Limit the search to the contents of my IQ library or my discount library. If not present the search is not restricted to those libraries only schema: type: string enum: - iq - discount example: discount - name: licenseType in: query required: false description: Limit the search to rights managed or royalty free content to include both omit this parameter schema: type: string enum: - rm - rf example: rm - name: propertyRelease in: query required: false description: Limit the search to only content with a property release if true schema: type: boolean example: true - name: modelRelease in: query required: false description: Limit the search to only content with a model release if true schema: type: boolean example: true - name: orientation in: query required: false description: | Limit the search to only content with an orientation matching the provided orientation(s). Orientation(s) should be supplied as an individual or comma separated list of the allowed values. Examples: `orientation=square` `orientation=landscape,panoramic` style: form explode: false schema: type: array uniqueItems: true items: type: string enum: - landscape - portrait - panoramic - square - name: includeCategory in: query required: false description: | Limit the results to the categories in the provided list of comma separated categories. Categories should be supplied as an individual or comma separated list of the allowed values. Examples: `includeCategory=Concepts` `includeCategory=Concepts,Education` style: form explode: false schema: type: array uniqueItems: true items: type: string enum: - Abstracts and backgrounds - Animals and wildlife - Architecture and interiors - Archive or historical - Art and artwork - Business - Celebrations and life events - Concepts - Education - Entertainment and celebrities - Food and drink - Healthcare and medical - Industry and agriculture - Landscapes - Lifestyle - News and reportage - Objects and still life - Occupations - Plants and gardens - Science - Sport - Technology - Transport - Travel - Weather and seasons - name: numberPeople in: query required: false description: | The number of people appearing in the content in the groups available from 1 through to 5 or more. 5 = a group of five or more people Number(s) should be supplied as an individual or comma separated list of the allowed values. Examples: `numberPeople=1` `numberPeople=2,3,4,5` style: form explode: false schema: type: array uniqueItems: true items: type: integer enum: - 1 - 2 - 3 - 4 - 5 - name: dateCreated in: query required: false description: The date the content was created schema: type: string format: date example: 2021-01-01 - name: dateCreatedSince in: query required: false description: The date & time the content was created since schema: type: string format: date example: 2021-01-01 - name: dateCreatedBefore in: query required: false description: The date & time the content was created before schema: type: string format: date example: 2021-01-02 - name: ethnicity in: query required: false description: | Limit the search to content of people of the supplied ethnicity/ethnicities. Enthnicities should be supplied as an individual or comma separated list of the allowed values. Examples: `ethnicity=Indian` `ethnicity=Brazilian,Colombian` style: form explode: false schema: type: array uniqueItems: true items: type: string enum: - AboriginalAustralian - Afghan - African - AfricanAmerican - AfroCaribbean - Albanian - Apache - Argentinean - Asian - AsianAndIndian - Baloch - Bolivian - Brazilian - Cambodian - Caucasian - CentralAsian - Cherokee - Chilean - Chinese - Colombian - Creole - Cuban - Dominican - EastAsian - EasternEuropean - Ecuadorian - Ethiopian - Filipino - Georgian - Haitian - Hawaiian - Indian - IndianSubcontinent - Indonesian - Iranian - Israeli - Italian - Jamaican - Japanese - Korean - Kurdish - LatinAmericanAndHispanic - Lebanese - Maldivian - Melanesian - Mexican - MiddleEastern - MixedRace - Mongolian - MultiEthnic - NativeAfrican - NativeAmerican - NativeNorth American - NativeSouth American - Nepalese - NezPerce - Nisei - NorthAfrican - NorthernEuropean - PacificIslander - Pakistani - Peruvian - Polynesian - PuebloanPeoples - Puerto Rican - Russian - Scandinavian - Sioux - SoutheastAsian - SouthernEuropean - SpanishAndPortuguese - SriLankan - Taiwanese - Tajiks - Thai - Tibetan - Trinidadian - Turkish - Uygur - Vietnamese - Zuni - name: age in: query required: false description: | Limit the search to content of people within the age range(s) provided. Age range(s) should be supplied as an individual or comma separated list of the allowed values. Examples: `age=twenties` `age=4-5Years,6-7Years,8-9Years` style: form explode: false schema: type: array uniqueItems: true items: type: string enum: - any - baby - toddler - child - 4-5Years - 6-7Years - 8-9Years - 10-11Years - 12-13Years - teenager - youngAdult - middleAged - matureAdult - adult - twenties - thirties - fourties - fifties - sixties - senior - name: viewpoint in: query required: false description: | Limit the search to content taken from the specified viewpoint(s). Viewpoint(s) should be supplied as an individual or comma separated list of the allowed values. Examples: `viewpoint=front` `viewpoint=side,profile` style: form explode: false schema: type: array uniqueItems: true items: type: string enum: - front - side - rear - profile - name: type in: query required: false description: | Limit the search to content of the specified type(s) of media item. Type(s) should be supplied as an individual or comma separated list of the allowed values. Default: `type=photograph,illustration,vector,threesixty` Examples: `type=photograph,illustration,threesixty` # `video` cannot be supplied alongside the other types. # Examples: `type=video` `type=photograph,illustration,threesixty` style: form explode: false schema: type: array uniqueItems: true items: type: string enum: - photograph - illustration - vector - threesixty # - video - name: order in: query required: false description: the sort order for the results of the search schema: type: string enum: - newest - newest-datetaken - relevant - creative - oldest-datetaken example: newest default: relevant # - name: fields # in: query # required: false # description: partial response filter to allow the return of only part of the response # schema: # type: string # example: items(uri) - name: safe in: query required: false description: Limit the search to only content which is safe to use and has all the required property and model releases in place schema: type: boolean example: true - name: collectiontype in: query required: false description: | Limit the search to content within the specified collection type(s). Collection type(s) should be supplied as an individual or comma separated list of the allowed values. Examples: `collectiontype=ultimate` `collectiontype=editorial-archive,editorial-core` **Deprecated:** `uncut` is deprecated and retained only for backward compatibility. It is no longer included in `all-creative`. schema: type: array uniqueItems: true items: type: string enum: - all-creative - ultimate - vital - uncut - foundation - editorial-archive - editorial-core - name: exclusive in: query required: false description: Limit the search to only content which is exclusive to Alamy schema: type: boolean - name: blackAndWhite in: query required: false description: Limit the search to only black and white content. Only applied when set to true; false or omitted values are ignored. schema: type: boolean example: true - name: by in: query required: false description: Limit the search to images taken by photographer or contributor of that name schema: type: string example: Andrey Kuzmin - name: resolution in: query required: false description: Comma separated list of video resolutions schema: type: string enum: - HD-720 - HD-1080 - 4k - 4k+ example: 'HD-1080' - name: frameRate in: query required: false description: Comma separated list of video frame rates schema: type: string enum: - '23.98' - '24' - '25' - '29.97' - '30' - '50+' example: '23.98' - name: durationStart in: query required: false description: The minimum duration of the video in seconds schema: type: integer example: 0 - name: durationEnd in: query required: false description: The maximum duration of the video in seconds schema: type: integer example: 60 - name: searchMode in: query required: false description: >- The search mode to use for the query. Defaults to text (textual matching against metadata) search when not specified. 'semantic' performs a search against the visual elements of the image only, 'hybrid' performs a combination of image and textual metadata search, 'smart' allows the service to detect and apply the most suitable searchMode for the query schema: type: string enum: - text - semantic - hybrid - smart default: text example: text responses: '200': description: successful operation # headers: # X-Rate-Limit-Limit: # description: The number of allowed requests in the current period # schema: # type: integer # example: 5000 # X-Rate-Limit-Remaining: # description: The number of remaining requests in the current period # schema: # type: integer # example: 4999 # X-Rate-Limit-Reset: # description: The number of seconds left in the current period # schema: # type: integer # example: 120 content: application/json: schema: $ref: '#/components/schemas/Items' examples: imageResponse: summary: Example response for an image search value: { 'offset': 2, 'limit': 2, 'totalResults': 36000, 'items': [ { 'standard': { 'name': 'ninjs', 'version': '2.0', 'schema': 'https://www.iptc.org/std/ninjs/ninjs-schema_2.0.json', }, 'uri': 'https://api.alamy.com/v3/item/343253265', 'type': 'picture', 'contentcreated': '2019-11-14T13:39:59Z', 'pubstatus': 'usable', 'representationtype': 'partial', 'descriptions': [ { 'role': 'caption', 'value': 'Dawn view at low tide with rowing boat in foreground, Plokton, near Kyle of Lochalsh, Highland, Scotland, United Kingdom, Europe', }, ], 'language': 'en', 'by': 'A Photographer', 'infosources': [ { 'name': 'A Photographer', 'literal': '9D111BD3-8175-453E-B451-65CFB0283C84', 'role': 'https://api.alamy.com/v3/roles/contributorPseudonym', }, ], 'renditions': [ { 'name': 'hires', 'title': 'High Resolution (JPG)', 'format': 'JPEG Baseline', 'href': 'https://api.alamy.com/v3/download/417951281', 'width': 4960, 'height': 3476, 'contenttype': 'image/jpeg', 'sizeinbytes': 1046951, }, { 'name': 'preview', 'title': 'Preview (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/comp/BK3BJK/dawn-view-at-low-tide-with-rowing-boat-in-foreground-plokton-near-BK3BJK.jpg', 'width': 1300, 'height': 956, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail450', 'title': 'Thumbnail 450 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/zooms/3/3d1d0e4ca7354b48a14556943f6cc1a9/bk3bjk.jpg', 'width': 450, 'height': 320, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail640', 'title': 'Thumbnail 640 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/zooms/9/3d1d0e4ca7354b48a14556943f6cc1a9/bk3bjk.jpg', 'width': 640, 'height': 447, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail170', 'title': 'Thumbnail 170 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/thumbs/bk3bjk/dawn-view-at-low-tide-with-rowing-boat-in-foreground-plokton-near-bk3bjk.jpg', 'width': 170, 'height': 113, 'contenttype': 'image/jpeg', }, ], 'altids': [ { 'role': 'id', 'value': 'A12BA442-2168-CCCF-9F78-8AE975045461', }, { 'role': 'seq', 'value': '417951281' }, { 'role': 'ref', 'value': 'BK3BJK' }, ], 'objects': [ { 'name': 'Rights managed', 'rel': 'usageDefinedBy', 'literal': 'rightsManaged', }, ], }, { 'standard': { 'name': 'ninjs', 'version': '2.0', 'schema': 'https://www.iptc.org/std/ninjs/ninjs-schema_2.0.json', }, 'uri': 'https://api.alamy.com/v3/item/343253266', 'type': 'picture', 'contentcreated': '2020-11-14T13:39:59Z', 'pubstatus': 'usable', 'representationtype': 'partial', 'descriptions': [ { 'role': 'caption', 'value': "Intha 'leg rowing' fishermen at sunset on Inle Lake, Inle Lake, Myanmar", }, ], 'language': 'en', 'by': 'A Photographer', 'infosources': [ { 'name': 'A Photographer', 'literal': '9D111BD3-8175-453E-B451-65CFB0283C84', 'role': 'https://api.alamy.com/v3/roles/contributorPseudonym', }, ], 'renditions': [ { 'name': 'hires', 'title': 'High Resolution (JPG)', 'format': 'JPEG Baseline', 'href': 'https://api.alamy.com/v3/download/343253266', 'width': 4960, 'height': 3476, 'contenttype': 'image/jpeg', 'sizeinbytes': 1046951, }, { 'name': 'preview', 'title': 'Preview (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/comp/DAD12R/intha-leg-rowing-fishermen-at-sunset-on-inle-lake-inle-lake-myanmar-DAD12R.jpg', 'width': 1300, 'height': 956, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail450', 'title': 'Thumbnail 450 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/zooms/3/b9d3a043a31d4f08a2df592cbce700fa/dad12r.jpg', 'width': 450, 'height': 320, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail640', 'title': 'Thumbnail 640 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/zooms/9/b9d3a043a31d4f08a2df592cbce700fa/dad12r.jpg', 'width': 640, 'height': 447, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail170', 'title': 'Thumbnail 170 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/thumbs/dad12r/intha-leg-rowing-fishermen-at-sunset-on-inle-lake-inle-lake-myanmar-dad12r.jpg', 'width': 170, 'height': 113, 'contenttype': 'image/jpeg', }, ], 'altids': [ { 'role': 'id', 'value': '83F00140-44BF-4D19-99B4-EABBA7601599', }, { 'role': 'seq', 'value': '343253266' }, { 'role': 'ref', 'value': '2AXCF16' }, ], 'objects': [ { 'name': 'Rights managed', 'rel': 'usageDefinedBy', 'literal': 'rightsManaged', }, ], }, ], } videoResponse: summary: Example response for a video search value: { 'offset': 2, 'limit': 2, 'totalResults': 98045, 'items': [ { 'standard': { 'name': 'ninjs', 'version': '2.0', 'schema': 'http://www.iptc.org/std/ninjs/ninjs-schema_2.0.json', }, 'uri': 'https://api.alamy.com/v3/item/419713942', 'type': 'video', 'firstcreated': '2021-04-23T14:59:43Z', 'contentcreated': '2019-03-11T00:00:00.000Z', 'representationtype': 'partial', 'pubstatus': 'usable', 'language': 'en', 'by': 'Pond5', 'descriptions': [ { 'role': 'caption', 'value': 'Starting a Car.', }, ], 'renditions': [ { 'name': 'hires', 'title': 'High Resolution', 'href': 'https://api.alamy.com/v3/download/419713942', 'width': 3840, 'height': 2160, 'duration': 6, }, { 'name': 'preview', 'title': 'Preview (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/comp/2farhbj/starting-a-car-2farhbj.jpg', 'width': 1300, 'height': 731, 'contenttype': 'image/jpeg', }, { 'name': 'previewVideo', 'title': 'Preview Video (MP4)', 'format': 'MPEG', 'href': 'https://p5resellerp.s3-accelerate.amazonaws.com/104386550.mp4', 'width': 960, 'height': 540, 'contenttype': 'video/mp4', 'duration': 6, }, { 'name': 'thumbnail450', 'title': 'Thumbnail 450 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/zooms/6/845ff23edcf54ffbad673dafa598675a/2FARHBJ.jpg', 'width': 450, 'height': 253, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail640', 'title': 'Thumbnail 640 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/zooms/9/845ff23edcf54ffbad673dafa598675a/2FARHBJ.jpg', 'width': 640, 'height': 360, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail170', 'title': 'Thumbnail 170 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/comp/2farhbj/starting-a-car-2farhbj.jpg', 'width': 170, 'height': 95, 'contenttype': 'image/jpeg', }, ], 'altids': [ { 'role': 'id', 'value': '845FF23E-DCF5-4FFB-AD67-3DAFA598675A', }, { 'role': 'seq', 'value': '419713942' }, { 'role': 'ref', 'value': '2FARHBJ' }, ], 'infosources': [ { 'name': 'Pond5', 'literal': '79205B12-C3A2-4116-A26C-38C074AF8F38', 'role': 'https://api.alamy.com/v3/roles/contributorPseudonym', }, ], 'objects': [ { 'name': 'Royalty free', 'rel': 'usageDefinedBy', 'literal': 'royaltyFree', }, ], }, { 'standard': { 'name': 'ninjs', 'version': '2.0', 'schema': 'http://www.iptc.org/std/ninjs/ninjs-schema_2.0.json', }, 'uri': 'https://api.alamy.com/v3/item/589129000', 'type': 'video', 'firstcreated': '2023-12-21T16:59:27Z', 'contentcreated': '2021-03-15T00:00:00.000Z', 'representationtype': 'partial', 'pubstatus': 'usable', 'rightsinfo': { 'linkedrights': 'https://api.alamy.com/v3/item/589129000', }, 'language': 'en', 'by': 'DepositPhotos', 'descriptions': [{ 'role': 'caption', 'value': 'Trip by car' }], 'renditions': [ { 'name': 'hires', 'title': 'High Resolution', 'href': 'https://api.alamy.com/v3/download/589129000', 'width': 3840, 'height': 2160, 'duration': 7, }, { 'name': 'preview', 'title': 'Preview (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/comp/2w6d41c/trip-by-car-2w6d41c.jpg', 'width': 1300, 'height': 731, 'contenttype': 'image/jpeg', }, { 'name': 'previewVideo', 'title': 'Preview Video (MP4)', 'format': 'MPEG', 'href': 'https://st2.depositphotos.com/thumbs/1003434/456783644/api_thumb_600.mp4', 'width': 960, 'height': 540, 'contenttype': 'video/mp4', 'duration': 7, }, { 'name': 'thumbnail450', 'title': 'Thumbnail 450 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/zooms/6/67606e119a5048a1b419a4bc9edf5d56/2W6D41C.jpg', 'width': 450, 'height': 253, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail640', 'title': 'Thumbnail 640 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/zooms/9/67606e119a5048a1b419a4bc9edf5d56/2W6D41C.jpg', 'width': 640, 'height': 360, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail170', 'title': 'Thumbnail 170 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/thumbs/2w6d41c/trip-by-car-2w6d41c.jpg', 'width': 170, 'height': 95, 'contenttype': 'image/jpeg', }, ], 'altids': [ { 'role': 'id', 'value': '67606E11-9A50-48A1-B419-A4BC9EDF5D56', }, { 'role': 'seq', 'value': '589129000' }, { 'role': 'ref', 'value': '2W6D41C' }, ], 'infosources': [ { 'name': 'DepositPhotos', 'literal': 'F6C7B625-3414-401B-A0A2-A500356A7982', 'role': 'https://api.alamy.com/v3/roles/contributorPseudonym', }, ], 'objects': [ { 'name': 'Royalty free', 'rel': 'usageDefinedBy', 'literal': 'royaltyFree', }, ], }, ], } '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Missing required request parameters: [q]' } '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Unauthorized' } '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Internal server error' } /item/{id}: get: tags: - Item security: - OAuth2: - item summary: Retrieve metadata for a single media item description: Returns the metadata for a single media item operationId: item parameters: - name: id in: path required: true description: The id of the media item to retrieve in either 'seq' format or 'ref' format. The 'seq' format is the numeric id of the media item and the 'ref' format is the short alphanumeric id of the media item. Both are shown as 'altids' within the item response. schema: oneOf: - type: string - type: integer # - name: fields # in: query # required: false # description: partial response filter to allow the return of only part of the response # schema: # type: string # example: uri responses: '200': description: successful operation # headers: # X-Rate-Limit-Limit: # description: The number of allowed requests in the current period # schema: # type: integer # example: 5000 # X-Rate-Limit-Remaining: # description: The number of remaining requests in the current period # schema: # type: integer # example: 4999 # X-Rate-Limit-Reset: # description: The number of seconds left in the current period # schema: # type: integer # example: 120 content: application/json: schema: $ref: '#/components/schemas/Ninjs' examples: imageResponse: summary: Example response for an image item value: { 'standard': { 'name': 'ninjs', 'version': '2.0', 'schema': 'https://www.iptc.org/std/ninjs/ninjs-schema_2.0.json', }, 'uri': 'https://api.alamy.com/v3/item/343253265', 'type': 'picture', 'version': '0', 'firstcreated': '2019-11-15T13:39:59Z', 'contentcreated': '2019-11-15T14:39:44Z', 'pubstatus': 'usable', 'rightsinfo': { 'langid': 'https://w3.org/ns/odrl/2/', 'encodedrights': '{"@context":["http://www.w3.org/ns/odrl.jsonld","https://api.alamy.com/v3/odrl-profile/alamy-rights.jsonld"],"@type":"Set","uid":"http://api.alamy.com/v3/rights/policy/2a:2b/99z:99y:2c:2d:2g:2e","profile":"https://api.alamy.com/v3/odrl-profile/","target":"http://api.alamy.com/v3/item/417951281","prohibition":[{"action":"alamy:advertisingCommercialUse"},{"action":"alamy:consumerGoodsUse"}],"permission":[{"action":"alamy:personalUse"},{"action":"alamy:commercialElectronicUse"},{"action":"alamy:directMailBrochuresUse"},{"action":"alamy:indoorDisplayUse"},{"action":"alamy:internalBusinessUse"},{"action":"alamy:editorialUse"}],"conflict":"invalid"}', }, 'representationtype': 'full', 'urgency': 5, 'language': 'en', 'descriptions': [ { 'role': 'creditline', 'value': 'Alamy' }, { 'role': 'caption', 'value': 'Dawn view at low tide with rowing boat in foreground, Plokton, near Kyle of Lochalsh, Highland, Scotland, United Kingdom, Europe', }, ], 'subjects': [ { 'rel': 'keyword', 'name': 'color image' }, { 'rel': 'keyword', 'name': 'dawn' }, { 'rel': 'keyword', 'name': 'lake' }, { 'rel': 'library', 'name': 'iqLibrary' }, ], 'title': 'Dawn view at low tide with rowing boat in foreground', 'objects': [ { 'rel': 'affectedBy', 'literal': 'blackAndWhite', 'name': 'Black and white', }, { 'rel': 'usageDefinedBy', 'literal': 'rightsManaged', 'name': 'Rights managed', }, ], 'by': 'A Photographer', 'infosources': [ { 'name': 'A Photographer', 'literal': '9D111BD3-8175-453E-B451-65CFB0283C84', 'role': 'https://api.alamy.com/v3/roles/contributorPseudonym', }, ], 'renditions': [ { 'name': 'hires', 'title': 'High Resolution (JPG)', 'format': 'JPEG Baseline', 'href': 'https://api.alamy.com/v3/download/417951281', 'width': 4960, 'height': 3476, 'contenttype': 'image/jpeg', 'sizeinbytes': 1046951, }, { 'name': 'preview', 'title': 'Preview (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/comp/BK3BJK/dawn-view-at-low-tide-with-rowing-boat-in-foreground-plokton-near-BK3BJK.jpg', 'width': 1300, 'height': 956, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail450', 'title': 'Thumbnail 450 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/zooms/3/3d1d0e4ca7354b48a14556943f6cc1a9/bk3bjk.jpg', 'width': 450, 'height': 320, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail640', 'title': 'Thumbnail 640 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/zooms/9/3d1d0e4ca7354b48a14556943f6cc1a9/bk3bjk.jpg', 'width': 640, 'height': 447, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail170', 'title': 'Thumbnail 170 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/thumbs/bk3bjk/dawn-view-at-low-tide-with-rowing-boat-in-foreground-plokton-near-bk3bjk.jpg', 'width': 170, 'height': 113, 'contenttype': 'image/jpeg', }, ], 'altids': [ { 'role': 'id', 'value': 'A12BA442-2168-CCCF-9F78-8AE975045461', }, { 'role': 'seq', 'value': '417951281' }, { 'role': 'ref', 'value': 'BK3BJK' }, ], } videoResponse: summary: Example response for a video item value: { altids: [ { role: 'id', value: '0880a7c2-b70e-42c0-8f1d-98c144604621', }, { role: 'seq', value: '572446580' }, { role: 'ref', value: '2T795CM' }, ], by: 'PA Video', contentcreated: '2018-09-28T12:05:35.000Z', descriptions: [ { role: 'creditline', value: 'Alamy' }, { role: 'caption', value: 'While essential maintenance checks are always wise, ensuring your car is in its best shape heading into winter is crucial. ', }, ], places: [ { name: 'N/A', rel: 'mentions', code: 'city:na', scheme: 'http://images-repository/v1/place', }, ], firstcreated: '2023-11-14T13:13:01.218Z', infosources: [ { name: 'PA Video', literal: '6a75c7e2-e198-4cd7-b014-aa9330603de1', role: 'https://api.alamy.com/v3/roles/contributorPseudonym', }, ], language: 'en', pubstatus: 'usable', renditions: [ { name: 'hires', title: 'High Resolution', href: 'https://api.alamy.com/v3/download/572446580', width: 1920, height: 1080, contenttype: 'video/mp4', sizeinbytes: 703819031, }, { name: 'thumbnail450', title: 'Thumbnail 450 (JPG)', format: 'JPEG Baseline', href: 'https://c7.alamy.com/450v/2t795cm/how-to-prepare-your-car-for-winter-2t795cm.jpg', width: 450, height: 253, contenttype: 'image/jpeg', }, { name: 'thumbnail640', title: 'Thumbnail 640 (JPG)', format: 'JPEG Baseline', href: 'https://c7.alamy.com/zooms/9/0880a7c2b70e42c08f1d98c144604621/2T795CM.jpg', width: 640, height: 360, contenttype: 'image/jpeg', }, { name: 'preview', title: 'Preview (JPG)', format: 'JPEG Baseline', href: 'https://c7.alamy.com/comp/2t795cm/how-to-prepare-your-car-for-winter-2t795cm.jpg', width: 1300, height: 731, contenttype: 'image/jpeg', }, { name: 'videopreview', title: 'Preview (MP4)', href: 'https://video-previews.alamy.com/2T795CM_572446580.mp4', width: 960, height: 540, contenttype: 'video/mp4', }, { name: 'thumbnail170', title: 'Thumbnail 170 (JPG)', format: 'JPEG Baseline', href: 'https://c7.alamy.com/thumbs/2t795cm/how-to-prepare-your-car-for-winter-2t795cm.jpg', width: 170, height: 95, contenttype: 'image/jpeg', }, ], representationtype: 'full', standard: { name: 'ninjs', schema: 'http://www.iptc.org/std/ninjs/ninjs-schema_2.0.json', version: '2.0', }, subjects: [ { name: 'car', rel: 'keyword' }, { name: 'consumer', rel: 'keyword' }, { name: 'tips', rel: 'keyword' }, { name: 'winter', rel: 'keyword' }, { name: 'winter driving', rel: 'keyword' }, { name: 'Transport', rel: 'category' }, ], title: 'How to prepare your car for winter', type: 'video', uri: 'https://api.alamy.com/v3/item/572446580', } '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Bad request: No item ID provided' } '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Unauthorized' } '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Your subscription does not include access to this item', } '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Not found' } '410': description: Gone content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'No longer available' } '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Internal server error' } /item: get: tags: - Item security: - OAuth2: - item summary: Retrieve metadata for multiple media items description: | Retrieve metadata for multiple media items. Note: category entries (`subjects[].rel == "category"`) are only emitted by the single-item endpoint (`GET /item/{id}`). The bulk response returns keyword subjects only. operationId: items parameters: - name: ids in: query required: true description: List of up to 500 media item IDs to retrieve metadata for in 'seq' format. 'seq' format is the numeric ID for the item. Invalid, incorrectly separated, duplicated, or more than 500 IDs provided will result in a 'bad request' response. schema: type: string example: '417951281,903050205,903050206' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/BulkItems' example: { 'items': [ { 'standard': { 'name': 'ninjs', 'version': '2.0', 'schema': 'https://www.iptc.org/std/ninjs/ninjs-schema_2.0.json', }, 'uri': 'https://api.alamy.com/v3/item/343253265', 'type': 'picture', 'version': '0', 'firstcreated': '2019-11-15T13:39:59Z', 'contentcreated': '2019-11-15T14:39:44Z', 'pubstatus': 'usable', 'rightsinfo': { 'langid': 'https://w3.org/ns/odrl/2/', 'encodedrights': '{"@context":["http://www.w3.org/ns/odrl.jsonld","https://api.alamy.com/v3/odrl-profile/alamy-rights.jsonld"],"@type":"Set","uid":"http://api.alamy.com/v3/rights/policy/2a:2b/99z:99y:2c:2d:2g:2e","profile":"https://api.alamy.com/v3/odrl-profile/","target":"http://api.alamy.com/v3/item/417951281","prohibition":[{"action":"alamy:advertisingCommercialUse"},{"action":"alamy:consumerGoodsUse"}],"permission":[{"action":"alamy:personalUse"},{"action":"alamy:commercialElectronicUse"},{"action":"alamy:directMailBrochuresUse"},{"action":"alamy:indoorDisplayUse"},{"action":"alamy:internalBusinessUse"},{"action":"alamy:editorialUse"}],"conflict":"invalid"}', }, 'representationtype': 'full', 'urgency': 5, 'language': 'en', 'descriptions': [ { 'role': 'creditline', 'value': 'Alamy' }, { 'role': 'caption', 'value': 'Dawn view at low tide with rowing boat in foreground, Plokton, near Kyle of Lochalsh, Highland, Scotland, United Kingdom, Europe', }, ], 'subjects': [ { 'rel': 'keyword', 'name': 'color image' }, { 'rel': 'keyword', 'name': 'dawn' }, { 'rel': 'keyword', 'name': 'lake' }, { 'rel': 'library', 'name': 'iqLibrary' }, ], 'title': 'Dawn view at low tide with rowing boat in foreground', 'objects': [ { 'rel': 'affectedBy', 'literal': 'blackAndWhite', 'name': 'Black and white', }, { 'rel': 'usageDefinedBy', 'literal': 'rightsManaged', 'name': 'Rights managed', }, ], 'by': 'A Photographer', 'infosources': [ { 'name': 'A Photographer', 'literal': '9D111BD3-8175-453E-B451-65CFB0283C84', 'role': 'https://api.alamy.com/v3/roles/contributorPseudonym', }, ], 'renditions': [ { 'name': 'hires', 'title': 'High Resolution (JPG)', 'format': 'JPEG Baseline', 'href': 'https://api.alamy.com/v3/download/417951281', 'width': 4960, 'height': 3476, 'contenttype': 'image/jpeg', 'sizeinbytes': 1046951, }, { 'name': 'preview', 'title': 'Preview (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/comp/BK3BJK/dawn-view-at-low-tide-with-rowing-boat-in-foreground-plokton-near-BK3BJK.jpg', 'width': 1300, 'height': 956, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail450', 'title': 'Thumbnail 450 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/zooms/3/3d1d0e4ca7354b48a14556943f6cc1a9/bk3bjk.jpg', 'width': 450, 'height': 320, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail640', 'title': 'Thumbnail 640 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/zooms/9/3d1d0e4ca7354b48a14556943f6cc1a9/bk3bjk.jpg', 'width': 640, 'height': 447, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail170', 'title': 'Thumbnail 170 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/thumbs/bk3bjk/dawn-view-at-low-tide-with-rowing-boat-in-foreground-plokton-near-bk3bjk.jpg', 'width': 170, 'height': 113, 'contenttype': 'image/jpeg', }, ], 'altids': [ { 'role': 'id', 'value': 'A12BA442-2168-CCCF-9F78-8AE975045461', }, { 'role': 'seq', 'value': '417951281' }, { 'role': 'ref', 'value': 'BK3BJK' }, ], }, ], 'unprocessed': ['903050205', '903050206'], 'totalRequested': 3, } '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Bad request' } '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Unauthorized' } '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Your subscription does not include access to items', } '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Internal server error' } /token: post: tags: - Authentication security: - BasicAuth: [] summary: Acquire access token based on client credentials description: Returns an expiring OAuth 2.0 access token to be used accessing search and download endpoints operationId: token requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: grant_type: type: string enum: - client_credentials example: 'client_credentials' scope: type: string enum: - https://api.alamy.com/v3/scopes/search - https://api.alamy.com/v3/scopes/item - https://api.alamy.com/v3/scopes/download example: 'https://api.alamy.com/v3/scopes/search' required: - grant_type responses: '200': description: Access token (Bearer) # headers: # X-Rate-Limit-Limit: # description: The number of allowed requests in the current period # schema: # type: integer # example: 5000 # X-Rate-Limit-Remaining: # description: The number of remaining requests in the current period # schema: # type: integer # example: 4999 # X-Rate-Limit-Reset: # description: The number of seconds left in the current period # schema: # type: integer # example: 120 content: application/json: schema: $ref: '#/components/schemas/Token' example: { 'access_token': '2YotnFZFEjr1zCsicMWpAA', 'token_type': 'Bearer', 'expires_in': 3600, } '400': description: Bad client credentials request content: application/json: schema: $ref: '#/components/schemas/TokenError' example: { 'error': 'invalid_client' } '401': description: Unauthorized '403': description: Access denied '500': description: Server error /download/{id}: get: tags: - Download security: - OAuth2: - download summary: Download a media item description: Returns a signed URL to download the specified media from operationId: downloadItemById parameters: - name: id in: path required: true description: The id of the media item to retrieve schema: type: integer responses: '200': description: JSON defining the download URL and expiry # headers: # X-Rate-Limit-Limit: # description: The number of allowed requests in the current period # schema: # type: integer # example: 5000 # X-Rate-Limit-Remaining: # description: The number of remaining requests in the current period # schema: # type: integer # example: 4999 # X-Rate-Limit-Reset: # description: The number of seconds left in the current period # schema: # type: integer # example: 120 content: application/json: schema: $ref: '#/components/schemas/Download' examples: imageResponse: summary: Example response for an image value: { 'url': 'https://download.alamy.com/345346sdggd/TETE232.jpg', 'expires_in_seconds': 3600, } videoResponse: summary: Example response for a video value: { 'url': 'https://pond5testurl/signed/path/to/video', 'expires_in_seconds': 1800, } '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Bad request: No item ID provided' } '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Unauthorized' } '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Your subscription does not include access to this item', } '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Not found' } '410': description: Gone content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'No longer available' } '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Internal server error' } post: tags: - Download security: - OAuth2: - download summary: Download a media item declaring the license it will be used with & optionally a pre-purchased pack for payment description: Returns a signed URL to download the specified media from. Records the license in use for the download and optionally authorises the download via a pre-purchased media type specific or mixed asset pack. operationId: downloadItemByIdLicensed parameters: - name: id in: path required: true description: The ID of the media item to retrieve schema: type: integer requestBody: required: true content: application/json: schema: type: object properties: licenseId: type: string format: uuid example: '519c5834-f7ae-4df6-83fe-19c5d857ab4c' description: 'ID of the license this download will be used with' packId: type: string format: uuid example: 'd92f7893-a866-ee11-ac7d-90b11c55b1bc' description: 'ID of the pre-paid pack which should be used to authorise this download' required: - licenseId responses: '200': description: JSON defining the download URL and expiry # headers: # X-Rate-Limit-Limit: # description: The number of allowed requests in the current period # schema: # type: integer # example: 5000 # X-Rate-Limit-Remaining: # description: The number of remaining requests in the current period # schema: # type: integer # example: 4999 # X-Rate-Limit-Reset: # description: The number of seconds left in the current period # schema: # type: integer # example: 120 content: application/json: schema: $ref: '#/components/schemas/Download' example: { 'url': 'https://download.alamy.com/345346sdggd/TETE232.jpg', 'expires_in_seconds': 3600, } '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Bad request: The provided license ID is not suitable for use with this item', } '402': description: Payment Required content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Payment required' } '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Unauthorized' } '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Your subscription does not include access to this item', } '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Not found' } '410': description: Gone content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'No longer available' } '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Internal server error' } /feed: get: tags: - Feed security: - OAuth2: - feed summary: Retrieve media item change notifications description: Returns a list of changes to media items since the optionally provided offset operationId: feed parameters: - name: offset in: query required: false description: The offset in milliseconds, notifications created after this millisecond will be retrieved schema: type: number - name: limit in: query required: false description: Amount of notifications, defaults to 10, maximum amount of 100 schema: type: number responses: '200': description: JSON with the list of notifications # headers: # X-Rate-Limit-Limit: # description: The number of allowed requests in the current period # schema: # type: integer # example: 5000 # X-Rate-Limit-Remaining: # description: The number of remaining requests in the current period # schema: # type: integer # example: 4999 # X-Rate-Limit-Reset: # description: The number of seconds left in the current period # schema: # type: integer # example: 120 content: application/json: schema: $ref: '#/components/schemas/FeedData' example: { 'offset': 1675773480000, 'limit': 10, 'nextPage': 'https://api.alamy.com/v3/feed?offset=1675780012679', 'items': [ { 'standard': { 'name': 'ninjs', 'version': '2.0', 'schema': 'https://www.iptc.org/std/ninjs/ninjs-schema_2.0.json', }, 'uri': 'https://api.alamy.com/v3/notification/3c40b5f8-da37-4513-8a4f-846370b54ab2', 'firstcreated': '2023-02-07T12:39:59.500Z', 'associations': [ { 'name': 'item', 'uri': 'https://api.alamy.com/v3/item/343253265', 'pubstatus': 'withheld', 'representationtype': 'partial', }, ], }, { 'standard': { 'name': 'ninjs', 'version': '2.0', 'schema': 'https://www.iptc.org/std/ninjs/ninjs-schema_2.0.json', }, 'uri': 'https://api.alamy.com/v3/notification/3c40b5f8-da37-4513-8a4f-846370b54ab0', 'firstcreated': '2023-02-07T13:39:59.500Z', 'associations': [ { 'name': 'item', 'uri': 'https://api.alamy.com/v3/item/343253265', 'type': 'picture', 'version': '0', 'firstcreated': '2019-11-15T13:39:59Z', 'contentcreated': '2019-11-15T14:39:44Z', 'pubstatus': 'usable', 'rightsinfo': { 'langid': 'https://w3.org/ns/odrl/2/', 'encodedrights': '{ "@context": [ "https://www.w3.org/ns/odrl.jsonld", "https://api.alamy.com/v3/odrl-profile/alamy-rights.jsonld" ], "@type": "Set", "uid": "https://api.alamy.com/v3/rights/policy/99z:2b", "profile": "https://api.alamy.com/v3/odrl-profile/", "target": "https://api.alamy.com/v3/item/343253265", "prohibition": [ { "action": [ "alamy:personalUse", "alamy:consumerGoodsUse" ] } ] }', }, 'representationtype': 'full', 'urgency': 5, 'language': 'en', 'descriptions': [ { 'role': 'creditline', 'value': 'Alamy' }, { 'role': 'caption', 'value': 'Dawn view at low tide with rowing boat in foreground, Plokton, near Kyle of Lochalsh, Highland, Scotland, United Kingdom, Europe', }, ], 'subjects': [ { 'rel': 'keyword', 'name': 'color image' }, { 'rel': 'keyword', 'name': 'dawn' }, { 'rel': 'keyword', 'name': 'lake' }, { 'rel': 'library', 'name': 'iqLibrary' }, ], 'title': 'Dawn view at low tide with rowing boat in foreground', 'objects': [ { 'rel': 'affectedBy', 'literal': 'blackAndWhite', 'name': 'Black and white', }, { 'rel': 'usageDefinedBy', 'literal': 'rightsManaged', 'name': 'Rights managed', }, ], 'altids': [ { 'role': 'id', 'value': 'B12BA442-2168-CCCF-9F78-8AE975045461', }, { 'role': 'seq', 'value': '343253265' }, { 'role': 'ref', 'value': 'BK3BJK' }, ], 'by': 'A Photographer', 'infosources': [ { 'name': 'A Photographer', 'literal': '9D111BD3-8175-453E-B451-65CFB0283C84', 'role': 'https://api.alamy.com/v3/roles/contributorPseudonym', }, ], 'renditions': [ { 'name': 'hires', 'title': 'High Resolution (JPG)', 'format': 'JPEG Baseline', 'href': 'https://api.alamy.com/v3/download/343253265', 'width': 4960, 'height': 3476, 'contenttype': 'image/jpeg', 'sizeinbytes': 1046951, }, { 'name': 'preview', 'title': 'Preview (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/comp/BK3BJK/dawn-view-at-low-tide-with-rowing-boat-in-foreground-plokton-near-BK3BJK.jpg', 'width': 1300, 'height': 956, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail450', 'title': 'Thumbnail 450 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/zooms/3/3d1d0e4ca7354b48a14556943f6cc1a9/bk3bjk.jpg', 'width': 450, 'height': 320, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail640', 'title': 'Thumbnail 640 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/zooms/9/3d1d0e4ca7354b48a14556943f6cc1a9/bk3bjk.jpg', 'width': 640, 'height': 447, 'contenttype': 'image/jpeg', }, { 'name': 'thumbnail170', 'title': 'Thumbnail 170 (JPG)', 'format': 'JPEG Baseline', 'href': 'https://c7.alamy.com/thumbs/bk3bjk/dawn-view-at-low-tide-with-rowing-boat-in-foreground-plokton-near-bk3bjk.jpg', 'width': 170, 'height': 113, 'contenttype': 'image/jpeg', }, ], }, ], }, ], } '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Bad request: Invalid offset provided' } '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Unauthorized' } '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Your subscription does not include access to feed', } '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Internal server error' } /orders: get: tags: - Orders security: - OAuth2: - orders summary: Retrieve user order history description: Returns a list of orders for the authenticated user. Supports long polling when dateFrom is provided - if no orders are found initially, the server will poll until orders arrive or timeout is reached. operationId: orders parameters: - name: limit in: query required: false description: Maximum number of orders to return per page (default 10) schema: type: integer example: 10 default: 10 - name: page in: query required: false description: Page number for pagination schema: type: integer example: 1 - name: dateFrom in: query required: false description: Filter orders created after this ISO 8601 datetime. Defaults to 24 hours ago when not provided. Must be within the last 365 days. When provided and no results are found, enables long polling mode. schema: type: string format: date-time example: '2024-01-01T00:00:00.000Z' - name: group in: query required: false description: Include orders from the user's group (organization) schema: type: boolean example: true responses: '200': description: JSON with the list of orders content: application/json: schema: $ref: '#/components/schemas/OrdersResponse' example: { 'nextPage': 'https://api.alamy.com/v3/orders?limit=10&page=2', 'items': [ { 'dateOrdered': '2024-01-15T10:30:00.000Z', 'uri': 'https://api.alamy.com/v3/item/123456789', 'downloadUrl': 'https://api.alamy.com/v3/download/123456789?orderNumber=order-123', }, { 'dateOrdered': '2024-01-16T11:30:00.000Z', 'uri': 'https://api.alamy.com/v3/item/123456790', 'downloadUrl': 'https://api.alamy.com/v3/download/123456790?orderNumber=order-124', }, ], } '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Bad request: dateFrom must be within the last 365 days' } '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Unauthorized' } '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Your subscription does not include access to orders', } '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/Error' example: { 'message': 'Internal server error' } components: securitySchemes: BasicAuth: type: http scheme: basic OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: 'https://api-auth.alamy.com/oauth/authorize' tokenUrl: 'https://api-auth.alamy.com/oauth/token' scopes: search: Grants access to archive search item: Grants access to media item(s) metadata download: Grants media item download access feed: Grants access to media item notifications orders: Grants access to order history schemas: Download: type: object properties: url: type: string description: Provides a signed URL to access the media item expires_in_seconds: type: integer format: int32 description: The lifetime in seconds of the access token OrdersResponse: type: object properties: nextPage: type: string description: URL for the next page of results, if available example: 'https://api.alamy.com/v3/orders?limit=10&page=2' items: type: array description: List of order items items: $ref: '#/components/schemas/OrderItem' required: - items OrderItem: type: object properties: dateOrdered: type: string format: date-time description: The date and time when the order was placed example: '2024-01-15T10:30:00.000Z' uri: type: string description: URL to the item endpoint for the ordered media item example: 'https://api.alamy.com/v3/item/123456789' downloadUrl: type: string description: URL to download the purchased media item example: 'https://api.alamy.com/v3/download/123456789?orderNumber=order-123' required: - dateOrdered - downloadUrl Token: type: object properties: access_token: type: string description: The access token value token_type: type: string enum: - Bearer description: Type of the token is set to "Bearer" expires_in: type: integer format: int32 description: The lifetime in seconds of the access token TokenError: type: object properties: error: type: string enum: - invalid_request - invalid_client - invalid_grant - unauthorized_client - unsupported_grant_type Ninjs: type: object title: IPTC ninjs - News in JSON - version 2.0 description: >- A news item as JSON object -- copyright 2021 IPTC - International Press Telecommunications Council - www.iptc.org - This document is published under the Creative Commons Attribution 4.0 license, see https://creativecommons.org/licenses/by/4.0/ additionalProperties: false required: - uri properties: uri: title: Uniform Resource Identifier description: >- The global unique identifier for this news object. This is the only required property and should identify the ninjs object, not be used for links to external resources etc. nar:newsItem@guid type: string format: uri type: title: Type description: >- The generic news type of this news object. (Value 'component' added in version 1.2 as issue #21.). See: https://cv.iptc.org/newscodes/ninature/ nar:itemClass type: string enum: - text - audio - video - picture - graphic - composite - component representationtype: title: Representation type description: >- Indicates how complete this representation of a news item is. No mapping to nar. Specific for ninjs. type: string enum: - full - partial profile: title: Profile description: >- An identifier for the structure of the news object. This can be any string but we suggest something identifying the structure of the content such as 'text-only' or 'text-photo'. Profiles are typically provider-specific. nar:profile type: string version: title: Version description: >- The version of the news object which is identified by the uri property. nar:newsItem@version type: string firstcreated: title: First created description: >- Indicates when the first version of this ninjs object was created. (Added in version 1.2 from issue #5). nar:firstCreated type: string format: date-time versioncreated: title: Version created description: >- The date and time when this version of this ninjs object was created. nar:versionCreated type: string format: date-time contentcreated: title: Content created description: >- The date and time when the content of this ninjs object was originally created. For example and old photo that is now handled as a ninjs object. nar:contentCreated type: string format: date-time embargoed: title: Embargoed description: >- The date and time before which all versions of the news object are embargoed. If absent, this object is not embargoed. nar:embargoed type: string format: date-time pubstatus: title: Publication status description: >- The publishing status of the news object, its value is *usable* by default. nar:pubStatus type: string enum: - usable - withheld - canceled urgency: title: Urgency description: >- The editorial urgency of the content. Values from 1 to 9. 1 represents the highest urgency, 9 the lowest. nar:urgency type: number copyrightholder: title: Copyright holder description: >- The person or organisation claiming the intellectual property for the content. nar:copyrightHolder type: string copyrightnotice: title: Copyright notice description: >- Any necessary copyright notice for claiming the intellectual property for the content. nar:copyrightNotice type: string usageterms: title: Usage terms description: >- A natural-language statement about the usage terms pertaining to the content. nar:usageTerms type: string ednote: title: Editorial note description: >- A note that is intended to be read by internal staff at the receiving organisation, but not intended to be published. (Added in version 1.2 from issue #6.). (Consider using this before using the descriptions array.) ednote: nar:edNote type: string language: title: Language description: >- The human language used by the content. The value should follow IETF BCP47. nar:language type: string descriptions: title: Descriptions description: >- An array of one or more descriptions of the ninjs object. See also ednote for information from provider to reciever. Descriptions are seen as metadata. For a simple description use an array with one object only containing the value property. Role and contenttype are then undefined and it is up to the provider. type: array items: type: object required: - value additionalProperties: false properties: role: title: Role description: The role of this description type: string contenttype: title: Content Type description: >- The IANA (Internet Assigned Numbers Authority) MIME type of the content of this description. type: string value: title: Value description: >- The descriptive text identified with the above role (and contenttype). type: string bodies: title: Bodies description: >- An array of body objects with the content as text or with markup. For a simple body use an array with one object only containing the value property. Role and contenttype are then undefined and it is up to the provider. type: array items: type: object required: - value additionalProperties: false properties: role: title: Role description: The role of this body type: string contenttype: title: Content Type description: >- The IANA (Internet Assigned Numbers Authority) MIME type of the content of this body. type: string charcount: title: Character count description: >- The total character count in this body excluding figure captions. (Added in version 1.2 according to issue #27.). nar:charcount type: number wordcount: title: Word count description: >- The total number of words in this body excluding figure captions. (Added in version 1.2 according to issue #27.). nar:wordcount type: number value: title: Value description: The body text identified with the above role and contenttype. type: string headlines: title: Headlines description: >- An array of objects containing various types of headlines. For a simple headline use an array with one object only containing the value property. Role and contenttype are then undefined and it is up to the provider. type: array items: type: object required: - value additionalProperties: false properties: role: title: Role description: The role of this headline type: string contenttype: title: Content Type description: >- The IANA (Internet Assigned Numbers Authority) MIME type of the content of this headline. type: string value: title: Value description: The headline identified with the above role and contenttype. type: string people: title: People description: 'An array of objects describing individual human beings. nar:subject' type: array items: type: object additionalProperties: false properties: name: title: Name description: The name of a person type: string rel: title: Relationship description: >- The relationship of the content of the news object to the person type: string uri: title: URI description: The identifier for the person as a complete uri with the code. type: string format: uri literal: title: Literal description: An identifier for the person as a free-text string. type: string organisations: title: Organisations description: >- An array of objects describing administrative and functional structures which may, for example, act as as a business, as a political party or not-for-profit party. nar:subject type: array items: type: object additionalProperties: false properties: name: title: Name description: The name of the organisation type: string rel: title: Relationship description: >- The relationship of the content of the news object to the organisation type: string uri: title: URI description: The identifier of the organisation as a complete uri type: string format: uri literal: title: Literal description: An identifier for the organisation as a free-text string. type: string symbols: title: Symbols description: >- Symbols used for a financial instrument linked to the organisation at a specific market place type: array items: type: object additionalProperties: false properties: ticker: title: Ticker description: Ticker symbol used for the financial instrument type: string exchange: title: Exchange description: >- Identifier for the marketplace which uses the ticker symbols of the ticker property type: string places: title: Places description: 'An array of named locations. nar:subject' additionalProperties: false type: array items: type: object anyOf: - properties: name: title: Name description: The name of the place type: string rel: title: Relationship description: >- The relationship of the content of the news object to the place type: string uri: title: URI description: The identifier for the place as a complete uri type: string format: uri literal: title: Literal description: An identifier for the place as a free-text string. type: string subjects: title: Subjects description: >- An array of objects holding concepts with a relationship to the content. nar:subject type: array items: type: object additionalProperties: false properties: name: title: Name description: The name of the subject type: string rel: title: Relationship description: >- The relationship of the content of the news object to the subject type: string uri: title: URI description: The identifier of the subject as a complete uri type: string format: uri literal: title: Literal description: An identifier for the subject as a free-text string. type: string events: title: Events description: >- An array of objects describing something which happens in a planned or unplanned manner. nar:? type: array items: type: object additionalProperties: false properties: name: title: Name description: The name of the event type: string rel: title: Relationship description: >- The relationship of the content of the news object to the event type: string uri: title: URI description: The identifier for the event as a complete uri type: string format: uri literal: title: Literal description: An identifier for the event as a free-text string. type: string objects: title: Objects description: >- An array of objects describing something material, excluding persons. nar:subject type: array items: type: object additionalProperties: false properties: name: title: Name description: The name of the object type: string rel: title: Relationship description: >- The relationship of the content of the news object to the object type: string uri: title: URI description: The identifier for the object as a complete uri type: string format: uri literal: title: Literal description: An identifier for the object as a free-text string. type: string infosources: title: Info sources description: >- An array of parties (person or organisation) which originated, modified, enhanced, distributed, aggregated or supplied the content or provided some information used to create or enhance the content. (Added in version 1.2 according to issue #15.) . infosource: nar:infoSource type: array items: type: object additionalProperties: false properties: name: title: Name description: The name of the infosource type: string role: title: Role description: >- The role the infosource in relationship to the content as a uri. type: string format: uri uri: title: URI description: The identifier of the infosource as a complete uri type: string format: uri literal: title: Literal description: An identifier for the infosource as a free-text string. type: string title: title: Title description: >- A short natural-language name for the item. Title is metadata, use headlines for publishable headlines. (Added in version 1.2 according to issue #9). nar:itemMeta/title type: string by: title: By description: >- A natural-language statement about the creator (author, photographer etc.) of the content. nar:by type: string slugline: title: Slugline description: >- A human-readable identifier for the item. (Added in version 1.2 from issue #4.). nar:slugline type: string located: title: Located description: >- The name of the location from which the content originates. nar:located type: string renditions: title: Renditions description: >- An array of objects with different renditions of the news object. nar:remoteContent type: array additionalProperties: false items: description: >- A specific rendition of the content of the news object. (Description changed in version 1.2 according to issue #17.) type: object additionalProperties: false required: - name properties: name: title: Name description: >- The name of this object in the array of renditions. For example 'thumbnail' type: string href: title: href description: >- The URL for accessing the rendition as a resource. nar:remoteContent@ref type: string format: uri contenttype: title: Content Type description: >- A MIME type which applies to this rendition. nar:remoteContent@contenttype type: string title: title: Title description: A title for the link to the rendition resource type: string height: title: Height description: >- For still and moving images: the height of the display area measured in pixels. nar:remoteContent@height type: number width: title: Width description: >- For still and moving images: the width of the display area measured in pixels. nar:remoteContent@width type: number sizeinbytes: title: Size in bytes description: The size of the rendition resource in bytes type: number duration: title: Duration description: >- The total time duration of the content in seconds. (Added in version 1.2. Issue #18). nar:remoteContent@duration type: number format: title: Format description: >- Binary format name. (Added in version 1.2. Issue #18). nar:remoteContent@format type: string associations: title: Associations description: >- An array of objects with content of news objects which are associated with this news object. type: array additionalProperties: false items: description: >- One associated object where each object can use all properties in ninjs. type: object anyOf: - properties: name: type: string description: >- The name of this object in the array of associations. For example 'logo' required: - name - $ref: '#/components/schemas/Ninjs' altids: title: Alternative ids description: >- Alternative identifiers assigned to the content. Each alternative id can have a role and a value. nar:altId issue #3. type: array items: type: object additionalProperties: false properties: role: title: Role description: The role of the alternative id type: string value: title: Value description: The alternative id value type: string trustindicators: title: Trust indicators description: >- An array of objects to allow links to documents about trust indicators. issue #44. (Added in version 1.3) type: array items: type: object additionalProperties: false properties: role: title: Role description: The role of the trust indicator as a complete uri type: string format: uri title: title: Title description: The title of the resource being referenced. type: string href: title: href description: The URL for accessing the trust indicator resource. type: string format: uri standard: title: Standard type: object description: >- An object with information about standard, version and schema this instance is valid against. nar:standard, nar:standardversion and xml:schema issue #43. (Added in version 1.3) additionalProperties: false properties: name: title: Name of standard. description: 'For example ninjs. nar:standard' type: string version: title: Version of standard. description: 'For example 1.3. nar:standardversion' type: string schema: title: Schema description: The uri of the json schema to use for validation. type: string format: uri genres: title: Genres description: >- A nature, intellectual or journalistic form of the content. nar:genre. (Added in version 1.3) type: array items: type: object additionalProperties: false properties: name: title: Name description: The name of the genre type: string uri: title: URI description: The identifier of the genre as a complete uri type: string format: uri literal: title: Literal description: An identifier for the genre as a free-text string. type: string rightsinfo: title: Rights information type: object description: 'Expression of rights to be applied to content. nar:rightsInfo' properties: langid: type: string title: Language id description: 'Identifier for the Rights Expression language used. nar:@langid' format: uri linkedrights: title: Linked rights description: >- A link from the current Item to Web resource with rights related information. nar:link type: string format: uri encodedrights: title: Encoded Rights additionalProperties: false type: string description: >- Contains a rights expression as defined by a Rights Expression Language. nar:rightsExpressionXML or nar:rightsExpressionData oneOf: - required: - linkedrights - required: - encodedrights NinjsSearchItem: type: object title: IPTC ninjs - News in JSON - version 2.0 description: 'A partial ninjs news item, as a JSON object, used in the search response' additionalProperties: false required: - uri properties: uri: title: Uniform Resource Identifier description: >- The global unique identifier for this news object. This is the only required property and should identify the ninjs object, not be used for links to external resources etc. nar:newsItem@guid type: string format: uri type: title: Type description: >- The generic news type of this news object. (Value 'component' added in version 1.2 as issue #21.). See: https://cv.iptc.org/newscodes/ninature/ nar:itemClass type: string enum: - text - audio - video - picture - graphic - composite - component representationtype: title: Representation type description: >- Indicates how complete this representation of a news item is. No mapping to nar. Specific for ninjs. type: string enum: - partial profile: title: Profile description: >- An identifier for the structure of the news object. This can be any string but we suggest something identifying the structure of the content such as 'text-only' or 'text-photo'. Profiles are typically provider-specific. nar:profile type: string contentcreated: title: Content created description: >- The date and time when the content of this ninjs object was originally created. For example and old photo that is now handled as a ninjs object. nar:contentCreated type: string format: date-time firstcreated: title: First created description: >- Indicates when the first version of this ninjs object was created. (Added in version 1.2 from issue #5). nar:firstCreated type: string format: date-time pubstatus: title: Publication status description: >- The publishing status of the news object, its value is *usable* by default. nar:pubStatus type: string enum: - usable - withheld - canceled rightsinfo: title: Rights information type: object description: >- Expression of rights to be applied to content. nar:rightsInfo properties: langid: type: string title: Language id description: >- Identifier for the Rights Expression language used. nar:@langid format: uri linkedrights: title: Linked rights description: >- A link from the current Item to Web resource with rights related information. nar:link type: string format: uri encodedrights: title: Encoded Rights additionalProperties: false type: string description: >- Contains a rights expression as defined by a Rights Expression Language. nar:rightsExpressionXML or nar:rightsExpressionData oneOf: - required: - linkedrights - required: - encodedrights language: title: Language description: >- The human language used by the content. The value should follow IETF BCP47. nar:language type: string descriptions: title: Descriptions description: >- An array of one or more descriptions of the ninjs object. See also ednote for information from provider to reciever. Descriptions are seen as metadata. For a simple description use an array with one object only containing the value property. Role and contenttype are then undefined and it is up to the provider. type: array items: type: object required: - value additionalProperties: false properties: role: title: Role description: The role of this description type: string contenttype: title: Content Type description: >- The IANA (Internet Assigned Numbers Authority) MIME type of the content of this description. type: string value: title: Value description: >- The descriptive text identified with the above role (and contenttype). type: string by: title: By description: >- A natural-language statement about the creator (author, photographer etc.) of the content. nar:by type: string infosources: title: Info sources description: 'An array of parties (person or organisation) which originated, modified, enhanced, distributed, aggregated or supplied the content or provided some information used to create or enhance the content. (Added in version 1.2 according to issue #15.) . infosource: nar:infoSource' type: array items: type: object additionalProperties: false properties: name: title: Name description: The name of the infosource type: string role: title: Role description: The role the infosource in relationship to the content as a uri. type: string format: uri uri: title: URI description: The identifier of the infosource as a complete uri type: string format: uri literal: title: Literal description: An identifier for the infosource as a free-text string. type: string renditions: title: Renditions description: >- An array of objects with different renditions of the news object. nar:remoteContent type: array additionalProperties: false items: description: >- A specific rendition of the content of the news object. (Description changed in version 1.2 according to issue #17.) type: object additionalProperties: false required: - name properties: name: title: Name description: >- The name of this object in the array of renditions. For example 'thumbnail' type: string href: title: href description: >- The URL for accessing the rendition as a resource. nar:remoteContent@ref type: string format: uri contenttype: title: Content Type description: >- A MIME type which applies to this rendition. nar:remoteContent@contenttype type: string title: title: Title description: A title for the link to the rendition resource type: string height: title: Height description: >- For still and moving images: the height of the display area measured in pixels. nar:remoteContent@height type: number width: title: Width description: >- For still and moving images: the width of the display area measured in pixels. nar:remoteContent@width type: number sizeinbytes: title: Size in bytes description: The size of the rendition resource in bytes type: number format: title: Format description: >- Binary format name. (Added in version 1.2. Issue #18). nar:remoteContent@format type: string duration: title: Duration type: number altids: title: Alternative ids description: >- Alternative identifiers assigned to the content. Each alternative id can have a role and a value. nar:altId issue #3. type: array items: type: object additionalProperties: false properties: role: title: Role description: The role of the alternative id type: string value: title: Value description: The alternative id value type: string standard: title: Standard type: object description: >- An object with information about standard, version and schema this instance is valid against. nar:standard, nar:standardversion and xml:schema issue #43. (Added in version 1.3) additionalProperties: false properties: name: title: Name of standard. description: 'For example ninjs. nar:standard' type: string version: title: Version of standard. description: 'For example 1.3. nar:standardversion' type: string schema: title: Schema description: The uri of the json schema to use for validation. type: string format: uri objects: title: Objects description: >- An array of objects describing something material, excluding persons. nar:subject type: array items: type: object additionalProperties: false properties: name: title: Name description: The name of the object type: string rel: title: Relationship description: >- The relationship of the content of the news object to the object type: string uri: title: URI description: The identifier for the object as a complete uri type: string format: uri literal: title: Literal description: An identifier for the object as a free-text string. type: string Items: type: object title: Alamy search response description: A search response containing an array of items if matches were found additionalProperties: false required: - items - offset - totalResults properties: offset: title: Offset within the results description: The current offset within the results type: integer limit: title: Limit description: The limit of items returned type: integer totalResults: title: Total results description: The number of matched items type: integer items: title: Matched items description: The items matching the search type: array items: $ref: '#/components/schemas/NinjsSearchItem' BulkItems: type: object description: | Response payload for `GET /item`. The bulk path returns the same Ninjs shape as the single-item endpoint with one exception: category entries (`subjects[].rel == "category"`) are only emitted by `GET /item/{id}`. The bulk response carries keyword subjects only — fetch `/item/{id}` if you need the category for a given item. required: - totalRequested properties: items: title: Matched items description: The items matching the requested image ids type: array items: $ref: '#/components/schemas/Ninjs' unprocessed: title: Unprocessed items description: List of unprocessed image ids type: array items: type: string totalRequested: title: Total requested description: The total number of items requested type: integer FeedData: type: object properties: offset: type: number description: Current offset limit: type: number description: Amount of items per page nextPage: type: string description: Link to fetch next offset of items items: type: array items: $ref: '#/components/schemas/Ninjs' Error: type: object required: - message properties: message: type: string example: message: Unauthorized