API Documentation

Introduction

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.

Authentication

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.

Endpoint Overview

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.

JavaScript SDK (beta)

If you're building a web-based application with the OpenAura API, you should take a look at our JavaScript SDK (beta). The JavaScript SDK (beta) greatly simplifies API interaction by wrapping REST calls and providing developers with data abstractions which make using the OpenAura API easy.

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.

Errors

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.

Explorer

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.

Glossary

Anchor
An anchor is any point at which we collect a set of particles to form an aura. Intuitively, anchors should be nouns as they form the fundamental point of entry for users making requests against the API for auras. The OpenAura API currently supports artist anchors.
Aura
An aura is a set of particles collected around an anchor by a relevance relationship. The fundamental activity of API consumers is requesting auras for specific anchors. A user may request an aura for an individual artist, for example. The API is expected to return a set of particles that can be used to create a visual experience which is relevant to the anchor.
Curator
A curator is a user associated with one or more anchors. A curator is able to influence the relevance relationship between particles and an anchor via the OpenAura curation tools.
Media
Media refers to the actual media object contained in a particle. In general, media will be a URI, although in some cases (such as text), the actual media is embedded in the API response.
Particle
A particle is the fundamental container for visual media delivered by the OpenAura API. A particle contains shared metadata for the attached media. While particles may contain multiple pieces of media and outbound links to other particles and anchors, a particle is generally meant to be visually displayed as a single unit.