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 <Openverse API token>\" \\\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 <Openverse API token>\" \\\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 <Openverse API token>\" \\\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 <Openverse API token>\" \\\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 <Openverse API token>\" \\\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 <Openverse API token>\" \\\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 <Openverse API token>\" \\\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 <Openverse API token>\" \\\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 <Openverse API token>\" \\\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 <Openverse API token>\" \\\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 <Openverse API token>\" \\\n \"https://api.openverse.org/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/related/\"\n"
/v1/images/{identifier}/report/:
post:
operationId: images
# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openverse/refs/heads/main/openapi/openverse-images-api-openapi.yml