openapi: 3.0.3 info: title: Openverse audio images API version: 909aa41ddf2115a69a447198b3f49121481e0c6b (v1) x-logo: url: https://raw.githubusercontent.com/WordPress/openverse/HEAD/documentation/meta/brand/logo.svg backgroundColor: '#fafafa' description: ' Openverse is a search engine for openly-licensed media. The Openverse API is a system that allows programmatic access to public domain digital media. It is our ambition to index and catalog billions of openly-licensed works, including articles, songs, videos, photographs, paintings, and more. Using this API, developers will be able to access the digital commons in their own applications. You can see some examples of [apps built with Openverse](https://docs.openverse.org/api/reference/made_with_ov.html) in our docs. ' termsOfService: https://docs.openverse.org/terms_of_service.html contact: name: Openverse email: openverse@wordpress.org license: name: MIT License url: https://github.com/WordPress/openverse/blob/main/LICENSE tags: - name: images description: These are endpoints pertaining to images. paths: /v1/images/: get: operationId: images_search description: ' Return images that match the query. This endpoint allows you to search within specific fields, or to retrieve a collection of all images from a specific source, creator or tag. Results are paginated on the basis of the `page` parameter. The `page_size` parameter controls the total number of pages. Although there may be millions of relevant records, only the most relevant or the most recent several thousand records can be viewed. This is by design: the search endpoint should be used to find the top 10,000 most relevant results, not for exhaustive search or bulk download of every barely relevant result. As such, the caller should not try to access pages beyond `page_count`, or else the server will reject the query. ### Default search The **default search** allows users to find media based on a query string. It supports a wide range of optional filters to narrow down search results according to specific needs. By default, this endpoint performs a full-text search for the value of `q` parameter. You can search within the `creator`, `title` or `tags` fields by omitting the `q` parameter and using one of these field parameters. These results can be filtered by `source`, `excluded_source`, `license`, `license_type`, `creator`, `tags`, `title`, `filter_dead`, `extension`, `mature`, `unstable__include_sensitive_results`, `category`, `aspect_ratio` and `size`. The default search results are sorted by relevance. ### Collection search The collection search allows to retrieve a collection of media from a specific source, creator or tag. The `unstable__collection` parameter is used to specify the type of collection to retrieve. - `unstable__collection=tag&unstable__tag=tagName` will return the media with tag `tagName`. - `unstable__collection=source&source=sourceName` will return the media from source `sourceName`. - `unstable__collection=creator&creator=creatorName&source=sourceName` will return the media by creator `creatorName` at `sourceName`. Collection results are sorted by the time they were added to Openverse, with the most recent additions appearing first. The filters such as `license` are not available for collections. ' externalDocs: description: Openverse Syntax Guide url: https://openverse.org/search-help parameters: - in: query name: page schema: type: integer minimum: 1 default: 1 description: The page of results to retrieve. This parameter is subject to limitations based on authentication and access level. For details, refer to [the authentication documentation](#tag/auth). - in: query name: page_size schema: type: integer minimum: 1 default: 20 description: Number of results to return per page. This parameter is subject to limitations based on authentication and access level. For details, refer to [the authentication documentation](#tag/auth). - in: query name: q schema: type: string title: query minLength: 1 description: A query string that should not exceed 200 characters in length - in: query name: source schema: type: string title: provider minLength: 1 description: ' For default search, a comma separated list of data sources. When the `unstable__collection` parameter is used, this parameter only accepts a single source. Valid values are `source_name`s from the stats endpoint: https://api.openverse.org/v1/images/stats/. ' - in: query name: excluded_source schema: type: string title: excluded_provider minLength: 1 description: ' A comma separated list of data sources to exclude from the search. Valid values are `source_name`s from the stats endpoint: https://api.openverse.org/v1/images/stats/. ' - in: query name: tags schema: type: string maxLength: 200 minLength: 1 description: Search by tag only. Cannot be used with `q`. The search is fuzzy, so `tags=cat` will match any value that includes the word `cat`. If the value contains space, items that contain any of the words in the value will match. To search for several values, join them with a comma. - in: query name: title schema: type: string maxLength: 200 minLength: 1 description: Search by title only. Cannot be used with `q`. The search is fuzzy, so `title=photo` will match any value that includes the word `photo`. If the value contains space, items that contain any of the words in the value will match. To search for several values, join them with a comma. - in: query name: creator schema: type: string maxLength: 200 minLength: 1 description: ' _When `q` parameter is present, `creator` parameter is ignored._ **Creator collection** When used with `unstable__collection=creator&source=sourceName`, returns the collection of media by the specified creator. Notice that a single creator''s media items can be found on several sources, but this collection only returns the items from the specified source. This is why for this collection, both the creator and the source parameters are required, and matched exactly. For a fuzzy creator search, use the default search without the `unstable__collection` parameter. **Creator search** When used without the `unstable__collection` parameter, will search in the creator field only. The search is fuzzy, so `creator=john` will match any value that includes the word `john`. If the value contains space, items that contain any of the words in the value will match. To search for several values, join them with a comma. ' - in: query name: unstable__collection schema: enum: - tag - source - creator type: string title: collection minLength: 1 description: ' _Caution: Parameters prefixed with `unstable__` are experimental and may change or be removed without notice in future updates. Use them with caution as they are not covered by our API versioning policy._ The kind of media collection to return. Must be used with `unstable__tag`, `source` or `creator`+`source` * `tag` - tag * `source` - source * `creator` - creator' - in: query name: unstable__tag schema: type: string title: tag maxLength: 200 minLength: 1 description: ' _Caution: Parameters prefixed with `unstable__` are experimental and may change or be removed without notice in future updates. Use them with caution as they are not covered by our API versioning policy._ _Must be used with `unstable__collection=tag`_ Get the collection of media with a specific tag. Returns the collection of media that has the specified tag, matching exactly and entirely. Differences that will cause tags to not match are: - upper and lower case letters - diacritical marks - hyphenation - spacing - multi-word tags where the query is only one of the words in the tag - multi-word tags where the words are in a different order. Examples of tags that **do not** match: - "Low-Quality" and "low-quality" - "jalapeño" and "jalapeno" - "Saint Pierre des Champs" and "Saint-Pierre-des-Champs" - "dog walking" and "dog walking" (where the latter has two spaces between the last two words, as in a typographical error) - "runner" and "marathon runner" - "exclaiming loudly" and "loudly exclaiming" For non-exact or multi-tag matching, using the `tags` query parameter. ' - in: query name: license schema: type: string title: licenses minLength: 1 description: 'A comma separated list of licenses; available licenses include: `by`, `by-nc`, `by-nc-nd`, `by-nc-sa`, `by-nd`, `by-sa`, `cc0`, `nc-sampling+`, `pdm`, and `sampling+`.' - in: query name: license_type schema: type: string minLength: 1 description: 'A comma separated list of license types; available license types include: `all`, `all-cc`, `commercial`, and `modification`.' - in: query name: filter_dead schema: type: boolean default: true description: Control whether 404 links are filtered out. - in: query name: extension schema: type: string minLength: 1 description: A comma separated list of desired file extensions. - in: query name: mature schema: type: boolean default: false description: Whether to include sensitive content. - in: query name: unstable__sort_by schema: enum: - relevance - indexed_on type: string default: relevance minLength: 1 description: ' _Caution: Parameters prefixed with `unstable__` are experimental and may change or be removed without notice in future updates. Use them with caution as they are not covered by our API versioning policy._ The field which should be the basis for sorting results. * `relevance` - Relevance * `indexed_on` - Indexing date' - in: query name: unstable__sort_dir schema: enum: - desc - asc type: string default: desc minLength: 1 description: ' _Caution: Parameters prefixed with `unstable__` are experimental and may change or be removed without notice in future updates. Use them with caution as they are not covered by our API versioning policy._ The direction of sorting. Cannot be applied when sorting by `relevance`. * `desc` - Descending * `asc` - Ascending' - in: query name: unstable__authority schema: type: boolean default: false title: authority description: ' _Caution: Parameters prefixed with `unstable__` are experimental and may change or be removed without notice in future updates. Use them with caution as they are not covered by our API versioning policy._ If enabled, the search will add a boost to results that are from authoritative sources.' - in: query name: unstable__authority_boost schema: type: number format: double maximum: 10.0 minimum: 0.0 default: 1.0 title: authority_boost description: ' _Caution: Parameters prefixed with `unstable__` are experimental and may change or be removed without notice in future updates. Use them with caution as they are not covered by our API versioning policy._ The boost coefficient to apply to authoritative sources, multiplied with the popularity boost.' - in: query name: unstable__include_sensitive_results schema: type: boolean default: false title: include_sensitive_results description: ' _Caution: Parameters prefixed with `unstable__` are experimental and may change or be removed without notice in future updates. Use them with caution as they are not covered by our API versioning policy._ Whether to include results considered sensitive.' - in: query name: category schema: type: string minLength: 1 description: 'A comma separated list of categories; available categories include: `digitized_artwork`, `illustration`, and `photograph`.' - in: query name: aspect_ratio schema: type: string minLength: 1 description: 'A comma separated list of aspect ratios; available aspect ratios include: `square`, `tall`, and `wide`.' - in: query name: size schema: type: string minLength: 1 description: 'A comma separated list of image sizes; available image sizes include: `large`, `medium`, and `small`.' tags: - images security: - Openverse API Token: [] - {} responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedImageList' examples: OK: value: result_count: 10000 page_count: 20 page_size: 20 page: 1 results: - id: 4bc43a04-ef46-4544-a0c1-63c63f56e276 title: Tree Bark Photo indexed_on: '2022-08-27T17:39:48Z' foreign_landing_url: https://stocksnap.io/photo/XNVBVXO3B7 url: https://cdn.stocksnap.io/img-thumbs/960w/XNVBVXO3B7.jpg creator: Tim Sullivan creator_url: https://www.secretagencygroup.com license: cc0 license_version: '1.0' license_url: https://creativecommons.org/publicdomain/zero/1.0/ provider: stocksnap source: stocksnap category: photograph filesize: 896128 filetype: jpg tags: - accuracy: null name: tree unstable__provider: stocksnap - accuracy: null name: bark unstable__provider: stocksnap - accuracy: null name: texture unstable__provider: stocksnap - accuracy: null name: wood unstable__provider: stocksnap - accuracy: null name: nature unstable__provider: stocksnap - accuracy: null name: pattern unstable__provider: stocksnap - accuracy: null name: rough unstable__provider: stocksnap - accuracy: null name: surface unstable__provider: stocksnap - accuracy: null name: brown unstable__provider: stocksnap - accuracy: null name: old unstable__provider: stocksnap - accuracy: null name: background unstable__provider: stocksnap - accuracy: null name: trunk unstable__provider: stocksnap - accuracy: null name: natural unstable__provider: stocksnap - accuracy: null name: forest unstable__provider: stocksnap - accuracy: null name: detail unstable__provider: stocksnap - accuracy: null name: lumber unstable__provider: stocksnap - accuracy: null name: weathered unstable__provider: stocksnap - accuracy: null name: timber unstable__provider: stocksnap - accuracy: null name: stump unstable__provider: stocksnap - accuracy: null name: closeup unstable__provider: stocksnap - accuracy: null name: root unstable__provider: stocksnap - accuracy: 0.95 name: tree unstable__provider: machine_example - accuracy: 0.9 name: bark unstable__provider: machine_example - accuracy: 0.98 name: plant unstable__provider: machine_example attribution: '"Tree Bark Photo" by Tim Sullivan is marked with CC0 1.0. To view the terms, visit https://creativecommons.org/publicdomain/zero/1.0/.' fields_matched: - title mature: false height: 4016 width: 6016 thumbnail: https://api.openverse.org/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/thumb/ detail_url: https://api.openverse.org/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/ related_url: https://api.openverse.org/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/related/ unstable__sensitivity: [] warnings: - code: partially invalid request parameter message: Some of the request parameters were bad, but we were able to process the request. Here's some information that might help you fix the problem for future requests. description: OK '400': content: application/json: schema: $ref: '#/components/schemas/ValidationError' examples: BadRequest: value: error: InputError detail: Invalid input given for fields. 'license' -> License 'PDMNBCG' does not exist. fields: - license summary: Bad Request description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/NotAuthenticated' examples: Unauthorized: value: detail: Authentication credentials were not provided. description: Unauthorized x-codeSamples: - lang: cURL source: "\n# Example 0: Search for images using single query parameter\ncurl \\\n -H \"Authorization: Bearer \" \\\n \"https://api.openverse.org/v1/images/?q=test\"\n\n\n# Example 1: Search for images using multiple query parameters\ncurl \\\n -H \"Authorization: Bearer \" \\\n \"https://api.openverse.org/v1/images/?q=test&license=pdm,by&categories=illustration&page_size=1&page=1\"\n\n\n# Example 2: Search for images that are an exact match of Claude Monet\ncurl \\\n -H \"Authorization: Bearer \" \\\n \"https://api.openverse.org/v1/images/?q=%22Claude%20Monet%22\"\n\n\n# Example 3: Search for images related to both dog and cat\ncurl \\\n -H \"Authorization: Bearer \" \\\n \"https://api.openverse.org/v1/images/?q=dog+cat\"\n\n\n# Example 4: Search for images related to dog or cat, but not necessarily both\ncurl \\\n -H \"Authorization: Bearer \" \\\n \"https://api.openverse.org/v1/images/?q=dog|cat\"\n\n\n# Example 5: Search for images related to dog but won't include results related to 'pug'\ncurl \\\n -H \"Authorization: Bearer \" \\\n \"https://api.openverse.org/v1/images/?q=dog -pug\"\n\n\n# Example 6: Search for images matching anything with the prefix ‘net’\ncurl \\\n -H \"Authorization: Bearer \" \\\n \"https://api.openverse.org/v1/images/?q=net*\"\n\n\n# Example 7: Search for images matching dogs that are either corgis or labrador\ncurl \\\n -H \"Authorization: Bearer \" \\\n \"https://api.openverse.org/v1/images/?q=dogs + (corgis | labrador)\"\n\n\n# Example 8: Search for images matching strings close to the term theaterwith a difference of one character\ncurl \\\n -H \"Authorization: Bearer \" \\\n \"https://api.openverse.org/v1/images/?q=theatre~1\"\n" /v1/images/{identifier}/: get: operationId: images_detail description: ' Get the details of a specified image. By using this endpoint, you can obtain info about images such as `id`, `title`, `indexed_on`, `foreign_landing_url`, `url`, `creator`, `creator_url`, `license`, `license_version`, `license_url`, `provider`, `source`, `category`, `filesize`, `filetype`, `tags`, `attribution`, `fields_matched`, `mature`, `height`, `width`, `thumbnail`, `detail_url`, `related_url` and `unstable__sensitivity`' parameters: - in: path name: identifier schema: type: string format: uuid required: true tags: - images security: - Openverse API Token: [] - {} responses: '200': content: application/json: schema: $ref: '#/components/schemas/Image' examples: OK: value: id: 4bc43a04-ef46-4544-a0c1-63c63f56e276 title: Tree Bark Photo indexed_on: '2022-08-27T17:39:48Z' foreign_landing_url: https://stocksnap.io/photo/XNVBVXO3B7 url: https://cdn.stocksnap.io/img-thumbs/960w/XNVBVXO3B7.jpg creator: Tim Sullivan creator_url: https://www.secretagencygroup.com license: cc0 license_version: '1.0' license_url: https://creativecommons.org/publicdomain/zero/1.0/ provider: stocksnap source: stocksnap category: photograph filesize: 896128 filetype: jpg tags: - accuracy: null name: tree unstable__provider: stocksnap - accuracy: null name: bark unstable__provider: stocksnap - accuracy: null name: texture unstable__provider: stocksnap - accuracy: null name: wood unstable__provider: stocksnap - accuracy: null name: nature unstable__provider: stocksnap - accuracy: null name: pattern unstable__provider: stocksnap - accuracy: null name: rough unstable__provider: stocksnap - accuracy: null name: surface unstable__provider: stocksnap - accuracy: null name: brown unstable__provider: stocksnap - accuracy: null name: old unstable__provider: stocksnap - accuracy: null name: background unstable__provider: stocksnap - accuracy: null name: trunk unstable__provider: stocksnap - accuracy: null name: natural unstable__provider: stocksnap - accuracy: null name: forest unstable__provider: stocksnap - accuracy: null name: detail unstable__provider: stocksnap - accuracy: null name: lumber unstable__provider: stocksnap - accuracy: null name: weathered unstable__provider: stocksnap - accuracy: null name: timber unstable__provider: stocksnap - accuracy: null name: stump unstable__provider: stocksnap - accuracy: null name: closeup unstable__provider: stocksnap - accuracy: null name: root unstable__provider: stocksnap - accuracy: 0.95 name: tree unstable__provider: machine_example - accuracy: 0.9 name: bark unstable__provider: machine_example - accuracy: 0.98 name: plant unstable__provider: machine_example attribution: '"Tree Bark Photo" by Tim Sullivan is marked with CC0 1.0. To view the terms, visit https://creativecommons.org/publicdomain/zero/1.0/.' fields_matched: [] mature: false height: 4016 width: 6016 thumbnail: https://api.openverse.org/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/thumb/ detail_url: https://api.openverse.org/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/ related_url: https://api.openverse.org/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/related/ unstable__sensitivity: [] description: OK '401': content: application/json: schema: $ref: '#/components/schemas/AuthenticationFailed' examples: Unauthorized: value: detail: Incorrect authentication credentials. description: Unauthorized '404': content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: NotFound: value: detail: Not found. summary: Not Found description: Not Found x-codeSamples: - lang: cURL source: "\n# Get the details of image ID 4bc43a04-ef46-4544-a0c1-63c63f56e276\ncurl \\\n -H \"Authorization: Bearer \" \\\n \"https://api.openverse.org/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/\"\n" /v1/images/{identifier}/related/: get: operationId: images_related description: ' Get related images for a specified image. By using this endpoint, you can get the details of related images such as `id`, `title`, `indexed_on`, `foreign_landing_url`, `url`, `creator`, `creator_url`, `license`, `license_version`, `license_url`, `provider`, `source`, `category`, `filesize`, `filetype`, `tags`, `attribution`, `fields_matched`, `mature`, `height`, `width`, `thumbnail`, `detail_url`, `related_url` and `unstable__sensitivity`.' parameters: - in: path name: identifier schema: type: string format: uuid required: true tags: - images security: - Openverse API Token: [] - {} responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedImageList' examples: OK: value: result_count: 10000 page_count: 20 page_size: 20 page: 1 results: - title: exam tactics id: 610756ec-ae31-4d5e-8f03-8cc52f31b71d creator: Sean MacEntee creator_url: https://www.flickr.com/photos/18090920@N07 tags: - name: exam - name: tactics url: https://live.staticflickr.com/4065/4459771899_07595dc42e.jpg thumbnail: https://api.openverse.org/v1/thumbs/610756ec-ae31-4d5e-8f03-8cc52f31b71d provider: flickr source: flickr license: by license_version: '2.0' license_url: https://creativecommons.org/licenses/by/2.0/ foreign_landing_url: https://www.flickr.com/photos/18090920@N07/4459771899 detail_url: https://api.openverse.org/v1/images/610756ec-ae31-4d5e-8f03-8cc52f31b71d related_url: https://api.openverse.org/v1/recommendations/images/610756ec-ae31-4d5e-8f03-8cc52f31b71d warnings: - code: partially invalid request parameter message: Some of the request parameters were bad, but we were able to process the request. Here's some information that might help you fix the problem for future requests. description: OK '401': content: application/json: schema: $ref: '#/components/schemas/AuthenticationFailed' examples: Unauthorized: value: detail: Incorrect authentication credentials. description: Unauthorized '404': content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: NotFound: value: detail: Not found. summary: Not Found description: Not Found x-codeSamples: - lang: cURL source: "\n# Get related images for image ID 4bc43a04-ef46-4544-a0c1-63c63f56e276\ncurl \\\n -H \"Authorization: Bearer \" \\\n \"https://api.openverse.org/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/related/\"\n" /v1/images/{identifier}/report/: post: operationId: images_report description: 'Report an issue about a specified image to Openverse. By using this endpoint, you can report an image if it infringes copyright, contains mature or sensitive content or some other reason.' parameters: - in: path name: identifier schema: type: string format: uuid required: true tags: - images requestBody: content: application/json: schema: $ref: '#/components/schemas/ImageReportRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/ImageReportRequest' multipart/form-data: schema: $ref: '#/components/schemas/ImageReportRequest' required: true security: - Openverse API Token: [] - {} responses: '201': content: application/json: schema: $ref: '#/components/schemas/ImageReportRequest' examples: Created: value: identifier: 4bc43a04-ef46-4544-a0c1-63c63f56e276 reason: mature description: Image contains sensitive content description: Created '401': content: application/json: schema: $ref: '#/components/schemas/AuthenticationFailed' examples: Unauthorized: value: detail: Incorrect authentication credentials. description: Unauthorized '400': content: application/json: schema: $ref: '#/components/schemas/ValidationError' examples: BadRequest: value: detail: : summary: Bad Request description: Bad Request '404': content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: NotFound: value: detail: Not found. summary: Not Found description: Not Found x-codeSamples: - lang: cURL source: "\n# Report an issue about image ID 4bc43a04-ef46-4544-a0c1-63c63f56e276\ncurl \\\n -X POST \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer \" \\\n -d '{\"reason\": \"mature\", \"description\": \"Image contains sensitive content\"}' \\\n \"https://api.openverse.org/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/report/\"\n" /v1/images/oembed/: get: operationId: images_oembed description: 'Retrieve the structured data for a specified image URL as per the [oEmbed spec](https://oembed.com/). This info can be used to embed the image on the consumer''s website. Only JSON format is supported.' parameters: - in: query name: url schema: type: string format: uri minLength: 1 description: The link to an image present in Openverse. required: true tags: - images security: - Openverse API Token: [] - {} responses: '200': content: application/json: schema: $ref: '#/components/schemas/Oembed' examples: OK: value: version: '1.0' type: photo width: 6016 height: 4016 title: Tree Bark Photo author_name: Tim Sullivan author_url: https://www.secretagencygroup.com license_url: https://creativecommons.org/publicdomain/zero/1.0/ description: OK '400': content: application/json: schema: $ref: '#/components/schemas/ValidationError' examples: BadRequest: value: detail: url: - Could not parse identifier from URL. summary: Bad Request description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/AuthenticationFailed' examples: Unauthorized: value: detail: Incorrect authentication credentials. description: Unauthorized '404': content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: NotFound: value: detail: Not found. summary: Not Found description: Not Found x-codeSamples: - lang: cURL source: "\n# Retrieve embedded content from an image's URL\ncurl \\\n -H \"Authorization: Bearer \" \\\n \"https://api.openverse.org/v1/images/oembed/?url=https://wordpress.org/openverse/photos/4bc43a04-ef46-4544-a0c1-63c63f56e276\"\n" /v1/images/stats/: get: operationId: images_stats description: ' Get a list of all content sources and their respective number of images in the Openverse catalog. By using this endpoint, you can obtain info about content sources such as `source_name`, `display_name`, `source_url`, `logo_url` and `media_count`.' tags: - images security: - Openverse API Token: [] - {} responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/Source' examples: OK: value: - source_name: flickr display_name: Flickr source_url: https://www.flickr.com logo_url: null media_count: 2500 description: OK '401': content: application/json: schema: $ref: '#/components/schemas/AuthenticationFailed' examples: Unauthorized: value: detail: Incorrect authentication credentials. description: Unauthorized x-codeSamples: - lang: cURL source: "\n# Get the statistics for image sources\ncurl \\\n -H \"Authorization: Bearer \" \\\n \"https://api.openverse.org/v1/images/stats/\"\n" components: schemas: ReasonEnum: enum: - mature - dmca - other type: string description: '* `mature` - mature * `dmca` - dmca * `other` - other' Image: type: object description: A single image. Used in search results. properties: id: type: string description: Our unique identifier for an open-licensed work. title: type: string nullable: true description: The name of the media. indexed_on: type: string format: date-time description: The timestamp of when the media was indexed by Openverse. foreign_landing_url: type: string nullable: true description: The landing page of the work. url: type: string nullable: true description: The actual URL to the media file. maxLength: 1000 creator: type: string nullable: true description: The name of the media creator. creator_url: type: string nullable: true description: A direct link to the media creator. maxLength: 2000 license: type: string description: The name of license for the media. maxLength: 50 license_version: type: string nullable: true description: The version of the media license. maxLength: 25 license_url: type: string nullable: true description: A direct link to the license deed or legal terms. readOnly: true provider: type: string nullable: true description: The content provider, e.g. Flickr, Jamendo... maxLength: 80 source: type: string nullable: true description: 'The source of the data, meaning a particular dataset. Source and provider can be different. Eg: the Google Open Images dataset is source=openimages, but provider=flickr.' maxLength: 80 category: type: string nullable: true description: The top-level classification of this media file. maxLength: 80 filesize: type: integer maximum: 2147483647 minimum: -2147483648 nullable: true description: Number in bytes, e.g. 1024. filetype: type: string nullable: true description: The type of the file, related to the file extension. maxLength: 80 tags: type: array items: $ref: '#/components/schemas/Tag' nullable: true description: Tags with detailed metadata, such as accuracy. attribution: type: string nullable: true description: Legally valid attribution for the media item in plain-text English. readOnly: true fields_matched: type: array items: {} nullable: true description: List the fields that matched the query for this result. mature: type: boolean description: Whether the media item is marked as mature height: type: integer maximum: 2147483647 minimum: -2147483648 nullable: true description: The height of the image in pixels. Not always available. width: type: integer maximum: 2147483647 minimum: -2147483648 nullable: true description: The width of the image in pixels. Not always available. thumbnail: type: string format: uri readOnly: true description: A direct link to the miniature artwork. detail_url: type: string format: uri readOnly: true description: A direct link to the detail view of this audio file. related_url: type: string format: uri readOnly: true description: A link to an endpoint that provides similar audio files. required: - attribution - detail_url - fields_matched - id - indexed_on - license - license_url - mature - related_url - tags - thumbnail Tag: type: object description: This output serializer serializes a singular tag. properties: name: type: string description: The name of a detailed tag. accuracy: type: number format: double nullable: true description: The accuracy of a machine-generated tag. Human-generated tags have a null accuracy field. unstable__provider: type: string nullable: true title: provider description: The source of the tag. When this field matches the provider for the record, the tag originated from the upstream provider. Otherwise, the tag was added with an external machine-generated labeling processes. required: - name - unstable__provider Source: type: object properties: source_name: type: string description: The source of the media, e.g. flickr display_name: type: string description: The name of content source, e.g. Flickr source_url: type: string format: uri description: The URL of the source, e.g. https://www.flickr.com logo_url: type: string nullable: true readOnly: true description: The URL to a logo for the source. deprecated: true media_count: type: integer readOnly: true description: The number of media items indexed from the source. required: - display_name - logo_url - media_count - source_name - source_url NotFound: title: NotFound type: object properties: detail: type: string description: A description of what went wrong. AuthenticationFailed: title: AuthenticationFailed type: object properties: detail: type: string description: A description of what went wrong. PaginatedImageList: type: object properties: result_count: type: integer description: The total number of items returned by search result. example: 10000 page_count: type: integer description: The total number of pages returned by search result. example: 20 page_size: type: integer description: The number of items per page. example: 20 page: type: integer description: The current page number returned in the response. example: 1 results: type: array items: $ref: '#/components/schemas/Image' warnings: type: array items: type: object description: Warnings pertinent to the request. If there are no warnings, this property will not be present on the response. Warnings are non-critical problems with the request. Responses with warnings should be treated as unstable. Warning descriptions must not be treated as machine readable and their schema can change at any time. example: - code: partially invalid request parameter message: Some of the request parameters were bad, but we were able to process the request. Here's some information that might help you fix the problem for future requests. required: - page_count - page_size - page - results - result_count ValidationError: title: ValidationError type: object properties: detail: oneOf: - type: string description: A description of what went wrong. - type: object additionalProperties: true ImageReportRequest: type: object properties: identifier: type: string format: uuid description: Our unique identifier for an open-licensed work. reason: allOf: - $ref: '#/components/schemas/ReasonEnum' description: 'The reason to report media to Openverse. * `mature` - mature * `dmca` - dmca * `other` - other' description: type: string nullable: true description: The explanation on why media is being reported. maxLength: 500 required: - identifier - reason NotAuthenticated: title: NotAuthenticated type: object properties: detail: type: string description: A description of what went wrong. TypeEnum: enum: - photo type: string VersionEnum: enum: - '1.0' type: string Oembed: type: object description: 'The embedded content from a specified image URL. This is essentially an ``ImageSerializer`` with some changes to match the oEmbed spec: https://oembed.com.' properties: version: allOf: - $ref: '#/components/schemas/VersionEnum' readOnly: true description: The oEmbed version number, always set to 1.0. type: allOf: - $ref: '#/components/schemas/TypeEnum' readOnly: true description: The resource type, always set to 'photo' for images. width: type: integer readOnly: true description: The width of the image in pixels. height: type: integer readOnly: true description: The height of the image in pixels. title: type: string nullable: true description: The name of the media. author_name: type: string description: The name of the media creator. author_url: type: string format: uri description: A direct link to the media creator. license_url: type: string nullable: true description: A direct link to the license deed or legal terms. readOnly: true required: - author_name - author_url - height - license_url - type - version - width securitySchemes: Openverse API Token: type: http scheme: bearer externalDocs: description: Openverse documentation url: http://docs.openverse.org/api/user/index.html