Introduction

Welcome to the Auracle Sound API! You can use our API to access API endpoints, which can get information on users, channels, etc.

You can view request and response examples in the area to the right.

Authentication

Sample request

GET https://player.auraclesound.com/api/me/ HTTP/1.1
Authorization: Bearer <access_token>

Auracle Sound expects for the access token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer <access_token>

Obtain an access token

Auracle Sound uses OAuth for obtaining user authorization.

Get the user’s permission

To initiate authentication flow, redirect your user to the following URL:

https://player.auraclesound.com/oauth/authorize/?client_id=<your_client_id>&response_type=code

The following query string parameters are available:

Parameter	Description
client_id	Your Client ID. required
response_type	Type of authorization flow. Must be code. required
state	Custom parameter that will be sent back in the redirect.
scope	Space-separated list of permissions the app is requesting.
redirect_uri	The URI to redirect the user to after successful authorization.

Redirect back to your app

After successful authorization, the user will be redirected to the specified URI:

https://example.com/oauth/?code=L4UgkgkAQuujkZUNrmGK2TuPhTVc9Hbp&state=abc123

The URI includes authorization code, which will be required in the next step.

Exchange the authorization code for an access token

Request

POST https://player.auraclesound.com/oauth/token/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code& /
code=GmIKC8nSmaSn0YYX9m0GWcVlZZXzzT& /
client_id=uoqjfY38sWqnQh9euL7rTKimwCDSl7J4u0VmFZjm& /
client_secret=t0gywG24UL8ptMfz2XLeKCYtKGk7psdKdu5aLjWzfnY5jzbsPT5NSB4kJmRU7XKUXCCrKmUNa8wT94wa2BhTXo5IkNvMVA2KtzNVPv1lwI3ZuGL7qSjZbGnJKHyrXNYa

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "access_token": "Kuhe3ziB8RmGXwAha1UfUiitMLha4myb",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "18iveZDwrPOrIGDQb5UX0mifUcN1kmtd",
  "scope": "user channels"
}

To exchange the authorization code for an access token, your app sends a POST request to the following URL:

https://player.auraclesound.com/oauth/token/

User

Get current user

Request

GET https://player.auraclesound.com/api/me/ HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "first_name": "John",
  "last_name": "Doe",
  "organisation_name": "ACME Ltd"
}

Returns current User.

User object

Field	Description	Sample value
first_name	User’s first name	"John"
last_name	User’s last name	"Doe"
organisation_name	User’s organisation name	"ACME Ltd"

HTTP Request

GET https://player.auraclesound.com/api/me/

Channels

Get current user’s channels

Request

GET https://player.auraclesound.com/api/me/channels/ HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 23,
    "name": "80s",
    "url": "http://stream3.auraclesoundstreams.com:8030/stream",
    "icon_url": "https://player.auraclesound.com/media/channel_icons/eighties.png",
    "image_url": "https://player.auraclesound.com/media/channel_covers/eighties.jpg",
    "favourite": false,
    "genres": ["disco"],
    "tags": ["#80s"]
    "iconURL": "https://player.auraclesound.com/media/channel_icons/eighties.png",
    "imageURL": "https://player.auraclesound.com/media/channel_covers/eighties.jpg",
  }
]

Channel object

Field	Description	Sample value
id	The channel’s ID	23
name	The channel’s name	"80s"
url	The URL of the stream	"http://stream3.auraclesoundstreams.com:8030/stream"
icon_url	The channel’s icon URL (see Cover images and icons)	"https://player.auraclesound.com/media/channel_icons/eighties.png"
image_url	The channel’s cover image URL (see Cover images and icons)	"https://player.auraclesound.com/media/channel_covers/eighties.jpg"
favourite	Whether the channel is in the user’s favourites	false
genres	The list of the channel’s genres	["disco"]
tags	Channel’s tags	["#80s"]
iconURL	deprecated Use icon_url	"https://player.auraclesound.com/media/channel_icons/eighties.png"
imageURL	deprecated Use image_url	"https://player.auraclesound.com/media/channel_covers/eighties.jpg"

HTTP Request

GET https://player.auraclesound.com/api/me/channels/

Cover images and icons

The channel’s image_url and icon_url are URLs to the original uploaded files. They may be very large, therefore inefficient to download every time your app presents a list of channels. You should use Auracle Sound’s resizing and caching endpoints. They will take care of creating and caching the images as well as invalidating the cache when an image changes.

Both endpoints require two paramers:

Parameter	Description	Sample value
channel_id	The ID of the channel	23
size	Required image size in pixels. All cover images and icons are square so it’s a single numerical value	128

Channel cover images

https://staging.player.auraclesound.com/media/images/channel/covers/<channel_id>_<size>.jpg

For example:

https://staging.player.auraclesound.com/media/images/channel/covers/23_128.jpg

This will return a 128px by 128px JPEG with the channel cover.

Channel icons

https://staging.player.auraclesound.com/media/images/channel/icons/<channel_id>_<size>.png

For example:

https://staging.player.auraclesound.com/media/images/channel/icons/23_128.png

This will return a 128px by 128px PNG with the channel icon.

Errors

The Auracle Sound API uses the following error codes:

Error Code	Error description	Meaning
400	Bad Request	Your request is invalid.
401	Unauthorized	Your access token is wrong.
402	Payment Required	The authenticated user doesn’t have a valid subscription and is out of trial period.
403	Forbidden	The authenticated user doesn’t have authorization to perform this request.
404	Not Found	The specified resource could not be found.
405	Method Not Allowed	The specified method cannot be performed on the resource.
429	Too Many Requests	You’re sending too many requests. Slow down.
500	Internal Server Error	We had a problem with our server. Try again later.
503	Service Unavailable	We're temporarily offline for maintenance. Please try again later.