The OpenAura API is built around REST principles. The API is designed around URI-based resources, which are accessible via HTTP verbs. All responses are JSON formatted data structures. The API supports cross-origin-resource-sharing, which allows users to use returned data directly in browser-based applications.
At the core of the OpenAura API response is a chunk of JSON data that we call a particle. Each particle represents a distinct visual resource along with metadata for that resource about attribution and licensing. A particle can represent a photograph uploaded by an artist, a Facebook image, a YouTube video, or any other piece of media available for a given artist.
The OpenAura API consists of a collection of endpoints that allow developers to make requests for this metadata in several different ways.
Structured information about the artist, including facts, a bio, and several artist images is provided via the /info endpoint. Our /particles endpoint provides a view directly into the stream of artist information, and allows developers to access custom sets of media responses using optional sorts and filters.
Developers can access the API via application-based keys. An API key must be provided in the api_key query string for all API requests. To get a free API key, complete the API key request form.
The following endpoints are available in the OpenAura API:
- /info - Detailed artist information including facts, bio and artist images
- /particles - Full stream of artist information
- /search - Artist search
- /source - Attribution information and metadata about content sources
Take a look at our examples and the API Explorer for detailed information about how to use the various endpoints and the structure of the responses.
You can take a look at our SDK documentation and download a minified version of the beta SDK for more detailed information. The source is available at GitHub.
The OpenAura API uses standard HTTP status codes to indicate the success or failure of requests. Successful requests should return a 2XX status code, and failures return 4XX, or 5XX error codes, depending on the type of error. In addition, error responses will include a JSON object with a descriptive message in the errorMessage field.
You can interactively explore the API endpoints and responses in the forms below. Try using '47' in the OpenAura artist id field (47 is Taylor Swift).
The demo API key is for use with the explorer only. Complete the request a key form to get your own free API key.