canonical: https://jentic.com/apis/openverse.org/openverse

# Openverse API (Creative Commons Catalog)

Openverse is a search engine for openly-licensed media - images and audio in the public domain or under Creative Commons licences. The REST API exposes search, detail, related items, thumbnails, oEmbed metadata, and source statistics for both images and audio, plus an OAuth2 application registration flow that grants higher rate limits via bearer tokens. Originally the Creative Commons Catalog API, Openverse aggregates more than 600 million openly-licensed works from sources like Wikimedia Commons, Flickr, and Smithsonian, and is maintained by the WordPress project.

## For AI agents

Search openly-licensed images and audio across hundreds of millions of works, fetch details, related items, thumbnails, and licence metadata.

## Scope

Does not handle video search, image generation, or paid stock photo libraries - use for openly-licensed image and audio search only.

## Capabilities

- Search public domain and Creative Commons images via /images with licence, source, and category filters
- Search openly-licensed audio via /audio with similar filters
- Retrieve detailed metadata for an image or audio item by identifier
- Get related items for a given image or audio identifier
- Pull thumbnails or audio waveform data via dedicated /thumb and /waveform endpoints
- Register an OAuth2 application via `/auth_tokens/register` and exchange credentials for a bearer token at `/auth_tokens/token`
- Inspect remaining rate-limit headroom via /rate_limit

## Use cases

### License-Safe Image Search for Editorial Tools

Editorial CMS plugins and content tools can call /images with a query string and licence filter to surface only commercially-usable, share-alike, or attribution-only images. Each returned record includes the licence URL, attribution string, and source so the editor can drop a properly attributed asset into a draft. The `/images/{identifier}` endpoint then exposes the full metadata including original filename and creator.

Example prompt: GET /images?q=mountain+sunset&license=cc0,by&page_size=20 and return each image's url, attribution, and license fields

### Open Audio Library for Podcasts and Apps

Podcast tools, education apps, and game studios needing freely-licensed background audio can search /audio with filters for licence, category (music, sound_effect), and length. Detail and waveform endpoints provide the data needed to render a usable preview before download. Aggregating across Wikimedia Commons, Jamendo, and other sources, Openverse covers material no single host catalogues alone.

Example prompt: GET /audio?q=ambient+forest&license=cc0&category=music&page_size=10 and return each track's url, attribution, and waveform_url

### OAuth2 Application for Higher Rate Limits

Production integrations should register an OAuth2 application via POST `/auth_tokens/register`, then exchange the client_id and client_secret at POST `/auth_tokens/token` for a bearer token. Bearer tokens unlock higher rate limits than anonymous calls. /rate_limit returns the remaining quota in the current window so the integration can throttle before hitting the cap.

Example prompt: POST `/auth_tokens/register` with name, description, and email, then POST `/auth_tokens/token` with client_credentials to obtain a bearer token

### AI Agent Open Media Discovery

An AI agent helping a user find license-safe imagery for a presentation can use Openverse through Jentic to filter by licence, attribution requirement, and source without managing OAuth flow. Jentic registers and refreshes tokens, dispatches /images or /audio searches, and returns structured JSON the agent can render with proper attribution.

Example prompt: Through Jentic, search 'find creative commons images', resolve to GET /images, and execute with q='climate change'&license=cc0

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/images` | Search openly-licensed images |
| GET | `/images/{identifier}` | Get image details by identifier |
| GET | `/images/{identifier}/thumb` | Fetch the image thumbnail |
| GET | `/audio` | Search openly-licensed audio |
| GET | `/audio/{identifier}` | Get audio details by identifier |
| GET | `/audio/{identifier}/waveform` | Get the audio waveform data |
| POST | `/auth_tokens/register` | Register an OAuth2 application |
| POST | `/auth_tokens/token` | Obtain a bearer token |

## Key resources

- **Images** — Search, detail, related, report, thumbnail, oEmbed, and source statistics for images.
- **Audio** — Search, detail, related, report, thumbnail, waveform, and source statistics for audio.
- **Auth Tokens** — Register an OAuth2 application and obtain bearer tokens.
- **Rate Limit** — Inspect remaining request quota for the current window.

## Why Jentic

- **Setup:** Wiring the Openverse API by hand means registering an application, exchanging your client credentials for a bearer token at `/auth_tokens/token`, and refreshing it before it expires. Through Jentic you install once, import the Openverse API from the API Directory, store the client credentials once, and your agent calls it while token refresh is handled for you.
- **Permission scoping:** Openverse search targets travel as request parameters rather than resource ids in the path, so scoping is by operation: you limit the agent to the operations it needs, such as image search or audio search, and leave the token-registration endpoints out unless you want them. Every operation the agent can call is one you chose to allow.
- **Credential handling:** Your Openverse client credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. The bearer token never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find creative commons images' or 'search openly licensed audio', and Jentic returns the matching Openverse operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Flickr API** — Flickr is one of Openverse's upstream sources; the Flickr API exposes richer per-photo metadata and uploads.
- **Freesound API** — Freesound is a Creative Commons audio archive with its own search and download API.
- **SoundCloud API** — SoundCloud hosts a wider audio catalogue, with mixed licensing - pair when CC-only is too restrictive.

## FAQ

### What authentication does the Openverse API use?

Openverse supports unauthenticated access at lower rate limits and OAuth2 bearer tokens for elevated limits. Tokens are obtained by registering an application at `/auth_tokens/register` and exchanging credentials at `/auth_tokens/token.` Through Jentic, client credentials are stored encrypted in the vault and the bearer token is refreshed automatically.

### Can I filter Openverse search results by license type?

Yes - both /images and /audio accept a license query parameter (e.g. cc0, by, by-sa) and a license_type parameter (commercial, modification). Each returned record includes the license, license_url, and attribution fields so downstream consumers can comply with the licence terms.

### What are the rate limits for the Openverse API?

Anonymous requests are limited to a smaller per-IP window; OAuth2 bearer tokens raise the limit substantially. /rate_limit returns the remaining quota for the current window so an integration can throttle proactively rather than reacting to 429 responses.

### How do I search for Creative Commons images through Jentic?

Search Jentic for 'search creative commons images', load the GET /images schema, and execute with q, license, and page_size parameters. Jentic returns structured JSON including licence and attribution fields per result.

### Does the Openverse API include video search?

Not in the current spec - Openverse covers images and audio. Video is on the project roadmap but is not exposed by this v1 API. For video, look at YouTube Data API or Vimeo's API depending on your licensing needs.

### How do I get a thumbnail for an Openverse image?

Call GET `/images/{identifier}/thumb` with the image's identifier. The response is the thumbnail bytes (an image), suitable for direct rendering in a UI without re-fetching the original full-resolution file.

### Can I limit what my agent is allowed to do with the Openverse API?

Yes. Because Openverse search targets travel as request parameters rather than ids in the path, your self-hosted Jentic One instance scopes access by operation, and your own rules decide which endpoints the agent may call. You can allow just the operations it needs, such as image search on GET /images or audio search on GET /audio, and leave the OAuth2 registration endpoints POST `/auth_tokens/register` and POST `/auth_tokens/token` out unless the agent must obtain its own token. Every operation the agent can reach is one you chose to permit, and the stored client credentials are injected at execution time rather than exposed to the agent.