NAV -image
bash javascript

Introduction

This documentation aims to provide all the information you need to work with the Resonate Recordings API.

Base URL

app.resonaterecordings.com

Authenticating requests

This API is authenticated by sending an Authorization header with the value "Bearer {YOUR_DEVICE_TOKEN}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

To generate a token for an existing user, use the sanctum/token endpoint.
To create a new account and generate its token use the register endpoint.

Endpoints

Create an Api Token

This endpoint will issue a Bearer token to a user to be used to authenticate requests to the API.

The response will include the authorization token for the specific user and device, please record this token as it will be needed to authenticate further requests to the API.

Example request:

curl -X POST \
    "app.resonaterecordings.com/api/v2/sanctum/token" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"email":"herp@mcderp.com","password":"sit","device_name":"Herp's iPhone"}'
const url = new URL(
    "app.resonaterecordings.com/api/v2/sanctum/token"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "email": "herp@mcderp.com",
    "password": "sit",
    "device_name": "Herp's iPhone"
}

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (201):

{
    "user": {
        "id": 2,
        "photo_url": "https:\/\/fakewebsite.com\/not-a-photo",
        "email": "herp@mcderp.com",
        "name": "Herp McDerp"
    },
    "token": "22|dR8tXMSbhcT0FgQoxrOSPqOMEE7SUcRPmCz2f8m2"
}

Request   

POST api/v2/sanctum/token

Body Parameters

email  string  
Email of a registered user.

password  string  
Password for a registered user.

device_name  string  
The name of the device making the request.

Register a User

This endpoint will register a new user, giving them a show titled "tbd" and a Bearer token.

The response will include information about the newly registered user as well as the authorization token. Please record this token as it will be needed to authenticate calls to the API from this device.

Example request:

curl -X POST \
    "app.resonaterecordings.com/api/v2/register" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"name":"Guglielmo Marconi","email":"marconi@resonate.com","password":"illum","device_name":"first-radio"}'
const url = new URL(
    "app.resonaterecordings.com/api/v2/register"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Guglielmo Marconi",
    "email": "marconi@resonate.com",
    "password": "illum",
    "device_name": "first-radio"
}

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (201):

{
    "user": {
        "id": 3,
        "name": "Guglielmo Marconi",
        "email": "marconi@resonate.com"
    },
    "token": "1895|bhcT0FgQoxrOSPqOMEE7SUcRPmCz2f8m2dR8tXMS"
}

Request   

POST api/v2/register

Body Parameters

name  string  
Name of the user.

email  string  
User's email.

password  string  
User's password.

device_name  string  
The name of the device making the request.

List Shows

requires authentication

Calling this endpoint will return a list of all shows associated with the user making the request.

Example request:

curl -X GET \
    -G "app.resonaterecordings.com/api/v2/shows" \
    -H "Authorization: Bearer {YOUR_DEVICE_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "app.resonaterecordings.com/api/v2/shows"
);

let headers = {
    "Authorization": "Bearer {YOUR_DEVICE_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
 {
     "id": 1,
     "name": "Culpable",
     "slug": "culpable",
     "photo_url": "https://avatar.example/culpable",
     "created_at": "2020-11-20T13:51:41.000000Z",
     "updated_at": "2020-11-20T13:51:41.000000Z"
 },
 {
     "id": 13,
     "name": "My First Podcast",
     "slug": "my-first-podcast",
     "photo_url": "https://avatar.example/my-first-podcast",
     "created_at": "2020-11-22T13:51:41.000000Z",
     "updated_at": "2020-11-22T13:51:41.000000Z"
 }
}

Request   

GET api/v2/shows

List Recordings

requires authentication

Use this endpoint to get a list of all recordings belonging to the specified team.

Example request:

curl -X GET \
    -G "app.resonaterecordings.com/api/v2/shows/1974/recordings" \
    -H "Authorization: Bearer {YOUR_DEVICE_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "app.resonaterecordings.com/api/v2/shows/1974/recordings"
);

let headers = {
    "Authorization": "Bearer {YOUR_DEVICE_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
 {
     "id": 6,
     "title": "How to Podcast: Episode 1",
     "encoded_url": "https://encodedurl.example"
 },
 {
     "id": 7,
     "title": "Podcasting: A Definitive Guide",
     "encoded_url": "https://anotherurl.example"
 }
}

Request   

GET api/v2/shows/{team}/recordings

URL Parameters

team  integer  
The id of the team for which you want to list recordings for.

Save a Recording

requires authentication

This endpoint allows you to submit a recording and save it in the Resonate App.

Example request:

curl -X POST \
    "app.resonaterecordings.com/api/v2/shows/eius/recordings" \
    -H "Authorization: Bearer {YOUR_DEVICE_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"title":"pariatur","filename":"vero","gcs_object":"et","mime_type":"rem","recording_session_id":"facilis","device":"et"}'
const url = new URL(
    "app.resonaterecordings.com/api/v2/shows/eius/recordings"
);

let headers = {
    "Authorization": "Bearer {YOUR_DEVICE_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "title": "pariatur",
    "filename": "vero",
    "gcs_object": "et",
    "mime_type": "rem",
    "recording_session_id": "facilis",
    "device": "et"
}

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Request   

POST api/v2/shows/{team}/recordings

URL Parameters

team  string  

Body Parameters

title  string  
The title of the recording.

filename  string  
The name of the recording file to be saved.

gcs_object  string  
URL to the Google Cloud Storage object.

mime_type  string  
Mime type of the recording.

recording_session_id  string optional  
If the recording is from a Remote Recording Session, supply the session id.

device  string optional  
The device which the recording is coming from. (Supported types: browser, dolby)

List Episodes

requires authentication

Use this endpoint to retrieve all the episodes for the specified team.

Example request:

curl -X GET \
    -G "app.resonaterecordings.com/api/v2/shows/1966/episodes" \
    -H "Authorization: Bearer {YOUR_DEVICE_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "app.resonaterecordings.com/api/v2/shows/1966/episodes"
);

let headers = {
    "Authorization": "Bearer {YOUR_DEVICE_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
 {
     "id": 10,
     "uuid": "16a4d80b-493c-41ec-8915-c8c308b12397",
     "user_id": 1019,
     "team_id": 1966,
     "title": "Case File",
     "photo_url": "http:\/\/megaphone-prod.s3.amazonaws.com\/podcasts\/98e190e6-9d12-11e9-8b92-1f71bcb5663d\/image\/uploads_2F1567970237102-27o5fji7p8q-8f0ce853692113462e5e6207b864a573_2FIMG_2034.JPEG",
     "season": null,
     "number": "14",
     "description": "<p>In this episode, we cover Christian\u2019s case file.</p>",
     "approver_id": 7,
     "episode_type": "full",
     "is_explicit": 1,
     "due_on": "2020-11-04T00:00:00.000000Z",
     "approved_at": "2019-09-09T04:05:00.000000Z",
     "published_at": "2019-09-09T04:05:00.000000Z",
     "created_at": "2019-09-08T00:00:00.000000Z",
     "updated_at": "2020-10-21T02:45:39.000000Z",
     "deleted_at": null,
     "is_live": false,
     "episode_credit": null,
     "master": {
         "id": 303,
         "gcs_object": "https:\/\/storage.googleapis.com\/uploads.resonaterecordings.com\/masters-of-data\/David Hafley - Intro - v2.wav",
         "filename": "David Hafley - Intro - v2.wav",
         "extension": "wav",
         "mime_type": "audio\/x-wav",
         "duration": 8373738383,
         "size": 39383838,
         "created_at": "2018-05-28T04:40:08.000000Z",
         "updated_at": "2018-05-28T04:40:18.000000Z"
     }
 }
}

Request   

GET api/v2/shows/{team}/episodes

URL Parameters

team  integer  
The id of the team for which you want to get a list of episodes for.

List Subscribers

requires authentication

Use this endpoint to get a list of all subscribers belonging to the specified show.

Example request:

curl -X GET \
    -G "app.resonaterecordings.com/api/v2/shows/1974/subscribers?email=test%40test.com&per_page=1&page=9" \
    -H "Authorization: Bearer {YOUR_DEVICE_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "app.resonaterecordings.com/api/v2/shows/1974/subscribers"
);

let params = {
    "email": "test@test.com",
    "per_page": "1",
    "page": "9",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Authorization": "Bearer {YOUR_DEVICE_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (201):


{
     "current_page": 1,
     "data": [
         {
             "id": 12,
             "uuid": "ddbd717a-6e21-4211-856a-260fda955e9b",
             "name": "Herp Derperson",
             "email": "herp@derp.com",
             "photo_url": "https://www.gravatar.com/avatar/b5d9433ecd08cc700f8cf12dfcb18dff.jpg?s=200&d=mm",
             "timezone": "America/New_York",
             "created_at": "2021-02-01T18:46:43.000000Z",
             "updated_at": "2021-02-01T18:48:44.000000Z",
             "rss_feed_url": "feeds.rr.tom/2/ddbd717a-6e21-4211-856a-260fda955e9b",
         }
     ],
     "first_page_url": "https://app.rr.tom/api/v2/shows/2/subscribers?page=1",
     "from": 1,
     "last_page": 1,
     "last_page_url": "https://app.rr.tom/api/v2/shows/2/subscribers?page=1",
     "links": [
         {
             "url": null,
             "label": "&laquo; Previous",
             "active": false
         },
         {
             "url": "https://app.rr.tom/api/v2/shows/2/subscribers?page=1",
             "label": 1,
             "active": true
         },
         {
             "url": null,
             "label": "Next &raquo;",
             "active": false
         }
     ],
     "next_page_url": null,
     "path": "https://app.rr.tom/api/v2/shows/2/subscribers",
     "per_page": 1,
     "prev_page_url": null,
     "to": 1,
     "total": 1
 }

Request   

GET api/v2/shows/{team}/subscribers

URL Parameters

team  integer  
The id of the show for which you want to list subscribers for.

Query Parameters

email  string optional  
filter the subscriptions.

per_page  integer optional  
the number of data objects per page.

page  integer optional  
the current page. Example 1

Create Subscriber

requires authentication

Use this endpoint to add a subscriber to the specified show

Example request:

curl -X POST \
    "app.resonaterecordings.com/api/v2/shows/176/subscribers" \
    -H "Authorization: Bearer {YOUR_DEVICE_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"name":"Herp Derperson","email":"herp@derp.com"}'
const url = new URL(
    "app.resonaterecordings.com/api/v2/shows/176/subscribers"
);

let headers = {
    "Authorization": "Bearer {YOUR_DEVICE_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Herp Derperson",
    "email": "herp@derp.com"
}

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (201):

{
    "id": 13,
    "email": "herp@derp.com",
    "name": "Herp Derperson",
    "rss_feed_url": "feeds.rr.tom\/2\/6adc6b29-5ef9-4b0a-9fce-b510c9059f37"
}

Request   

POST api/v2/shows/{team}/subscribers

URL Parameters

team  integer  
The id of the show adding subscriber to

Body Parameters

name  string  
The name of the subscriber.

email  string  
The email of the subscriber.

Remove Subscriber

requires authentication

This endpoint will remove a subscriber from a specified show.

Example request:

curl -X DELETE \
    "app.resonaterecordings.com/api/v2/shows/176/subscribers" \
    -H "Authorization: Bearer {YOUR_DEVICE_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"name":"Herp Derperson","email":"herp@derp.com"}'
const url = new URL(
    "app.resonaterecordings.com/api/v2/shows/176/subscribers"
);

let headers = {
    "Authorization": "Bearer {YOUR_DEVICE_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Herp Derperson",
    "email": "herp@derp.com"
}

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (204):

<Empty response>

Request   

DELETE api/v2/shows/{team}/subscribers

URL Parameters

team  integer  
The id of the show removing the subscriber from

Body Parameters

name  string  
The name of the user who will be unsubscribed.

email  string  
The email of the user who will be unsubscribed.

Post a Comment

requires authentication

Use this endpoint to post a new comment to an episode.

Example request:

curl -X POST \
    "app.resonaterecordings.com/api/v2/episodes/1862/comments" \
    -H "Authorization: Bearer {YOUR_DEVICE_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"body":"Please remove my coughs."}'
const url = new URL(
    "app.resonaterecordings.com/api/v2/episodes/1862/comments"
);

let headers = {
    "Authorization": "Bearer {YOUR_DEVICE_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "body": "Please remove my coughs."
}

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (201):

{
    "id": 1,
    "body": "Please remove my coughs.",
    "user": {
        "name": "Herp Derperson",
        "email": "herp@derp.com"
    },
    "created_at": "2020-10-22T14:59:17.000000Z",
    "updated_at": "2020-10-22T14:59:17.000000Z"
}

Request   

POST api/v2/episodes/{episode}/comments

URL Parameters

episode  integer  
The id of the episode being commented on.

Body Parameters

body  string  
The body of the comment.

submission_incomplete  boolean optional  
Include this parameter when changing the completeness status of an episode.

revision_requested  boolean optional  
Include this parameter when requesting a revision to the episode.

List Comments

requires authentication

This endpoint will return all the comments on an episode.

Example request:

curl -X GET \
    -G "app.resonaterecordings.com/api/v2/episodes/1444/comments" \
    -H "Authorization: Bearer {YOUR_DEVICE_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "app.resonaterecordings.com/api/v2/episodes/1444/comments"
);

let headers = {
    "Authorization": "Bearer {YOUR_DEVICE_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
 {
     "id": 266,
     "body": "This episode is great! Love the unpredictability.",
     "user": {
         "name": "John Nash",
         "email": "nash@resonate.com"
     },
     "created_at": "2019-09-19T00:00:00.000000Z",
     "updated_at": "2019-09-19T00:00:00.000000Z"
 },
 {
     "id": 341,
     "body": "Thanks, it took me a while to get this set!",
     "user": {
         "name": "Benoit Mendelbrot",
         "email": "mendelbrot@resonate.com"
     },
     "created_at": "2019-09-20T00:00:00.000000Z"
     "updated_at": "2019-09-20T00:00:00.000000Z"
 }
}

Request   

GET api/v2/episodes/{episode}/comments

URL Parameters

episode  integer  
The id of the episode you wish to retrieve the comments of.

Save a Recording Session

requires authentication

This will create and save a new recording session for the remote recorder. It returns the created RecordingSession object.

Example request:

curl -X POST \
    "app.resonaterecordings.com/api/v2/recording-sessions" \
    -H "Authorization: Bearer {YOUR_DEVICE_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"team_id":1,"dolby_conf_id":"ut","dolby_conf_alias":"reiciendis"}'
const url = new URL(
    "app.resonaterecordings.com/api/v2/recording-sessions"
);

let headers = {
    "Authorization": "Bearer {YOUR_DEVICE_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "team_id": 1,
    "dolby_conf_id": "ut",
    "dolby_conf_alias": "reiciendis"
}

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (201):

{
    "id": 7,
    "team_id": 89,
    "owner_id": 33,
    "dolby_conf_id": "fe7b4a44-7935-473c-a29b-5e5a2f83ca2b",
    "dolby_conf_alias": "My Cool Conference"
}

Request   

POST api/v2/recording-sessions

Body Parameters

team_id  integer  
The id of the team the user is a member of.

dolby_conf_id  string  
The id of the Dolby conference initiated by the user.

dolby_conf_alias  string  
The alias of the Dolby conference initiated by the user.