AuracleAPI

AuracleAPI Quickstart

AuracleAPI is a public read-only REST API for artist identity data. It exposes profiles, group memberships, connected platform accounts, media, events, and more. All endpoints described here are unauthenticated and freely accessible.

For the full interactive reference, see API Reference.

Core Concepts

Auracle ID

An Auracle ID is a short, human-readable handle (e.g. AURA01JE38RP4ES) that resolves to a human, persona, collaboration, work or attribution. It can be used interchangeably with UUIDs in most lookup endpoints.

Personas

A persona is an individual artist profile and represents a public artistic identity. Some humans present multiple artistic identities of themselves, so may have multiple personas. By default, each user has one "professional profile" persona, and may add other artistic personas.

Key fields:

Field Description
persona_id UUID — primary API identifier for the persona
passport_id UUID — primary identifier for the human account.
auracle_id Human readable industry identifier for the persona
artist_name Display name
biography_* Short, long, and headline biographies
genres List of genre strings
music_roles Roles the artist performs (e.g. producer, vocalist)
instruments_* / tools_* Lists of instruments *_used or *_owned
connected_accounts Platform account links (Spotify, SoundCloud, etc.)
event_performances Past/future event appearances
representatives Linked manager/label/agent personas
official_links External URLs (website, social, etc.)

Collaborations

A collaboration is a group artist profile — a duo, band, choir, ensemble, or any multi-artist entity. It shares most fields with a persona and adds group-specific data.

Additional fields:

Field Description
collaboration_id UUID — primary identifier for the collaboration
collaboration_type One of: duo, band, choir, ensemble, orchestra, other
founding_date ISO 8601 date the group was formed
memberships List of CollabMembership objects (see reference)
owner_passport_id Passport UUID of the member who created the collaboration
migrated_from_persona_id Set when this collaboration was converted from a persona

Endpoints

Search

All search endpoints accept a query string and support offset / limit pagination.

Method Path Returns
GET /search/artists/?query=xxx Mixed list of personas and collaborations
GET /search/personas/ Personas only
GET /search/collaborations/ Collaborations only

Returns 404 when the query produces no results after exhausting all search strategies.

Personas

Method Path Returns
GET /artist/personas/ Paginated list of public personas
GET /artist/personas/{persona_id}/ Single persona by UUID
GET /artist/personas/auracle/{auracle_id}/ Persona by Auracle ID handle

Collaborations

Method Path Returns
GET /artist/collaborations/ Paginated list of public collaborations
GET /artist/collaborations/{collaboration_id}/ Single collaboration by UUID

Auracle ID

Method Path Returns
GET /artist/auracle/{auracle_id}/ Persona or passport resolved from handle

Events

Method Path Returns
GET /artist/personas/{persona_id}/events/ Events linked to a persona

Media

Method Path Returns
GET /artist/personas/{persona_id}/media/ Media items linked to a persona
GET /artist/collaborations/{collaboration_id}/media/ Media items linked to a collaboration

Access Contexts

Some persona and collaboration fields are gated by the access context supplied in a request. Public API calls use the public_page context by default.

Context Description
public_page Default unauthenticated access — standard public fields only
web_interface Authenticated user viewing their own data in the web app
partner_context_a Authenticated access via partner integration (OAuth2.0 / OIDC)

Collaboration Membership

Each entry in memberships follows CollabMembershipSchema:

Field Description
persona_id UUID of the member persona
passport_id UUID of the member's passport (user account)
instruments_played Instruments this member contributes in this collaboration
tools_used Software/hardware tools used in this collaboration
music_roles Roles performed within the collaboration
member_confirmed true when the member has accepted the membership invite
join_leave_dates List of date-range objects recording membership periods
rbac_roles Permission roles within the collaboration (e.g. owner, editor)

Data Linking

Objects are linked via UUIDs. Common traversal patterns:

Further Reading