NAV Navbar
Logo
shell python javascript

Introduction

Welcome to the Roundware API V2! You can use our API to access Roundware API endpoints, which act as the gateway to the Roundware audio augmented reality platform.

We have language bindings in Shell, Javascript and Python! You can view code examples for the Vagrant environment in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Initial testing setup

  1. Run POST api/2/users/ to get token
  2. Use token for all subsequent api calls
  3. Run POST api/2/sessions/

Authentication

Roundware requires tokenized users to access all endpoints other than users/.

Roundware’s default behavior is to create anonymous user accounts such that end users are not required to actively create accounts thereby reducing the barriers to participating in projects.

We are specifically designing the user system to allow for the eventual “claiming” of user accounts such that in the future we can allow participants to keep track of their contributions, get metrics on how their contributions have been accessed and other useful and encouraging information.

Roundware freely issues tokens and uses them not only for API request authorization, but also for throttling via Django REST Framework. However, in order to make POST PATCH and DELETE requests, a user must be assigned Staff status within Django’s Authentication and Authorization system. By default anonymous accounts created by POST users/ are not Staff.

Roundware API V2 expects for the token to be included in all API requests to the server in a header that looks like the following:

Authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4

users/

POST users/

import requests

url = "http://localhost:8888/api/2/users/"

payload = ""
response = requests.request("POST", url, data=payload)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/users/ \
  --header 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW'
var form = new FormData();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/users/",
  "method": "POST",
  "headers": {},
  "processData": false,
  "contentType": false,
  "mimeType": "multipart/form-data",
  "data": form
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "username": "14922898319281",
  "token": "4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
}

Create new User.

HTTP Request

POST localhost:8888/api/2/users/

Request Parameters

Parameter Sample Data Default Description/Notes
device_id* 123456 none unique id generated on client and preferably consistent between sessions
client_type iPhone none
client_system iOS 10.2 none

assets/

Definition:

An individual piece of media contributed by a user or by project administrators. Roundware currently handles audio, photo and text assets.

GET assets/

import requests

url = "http://localhost:8888/api/2/assets/"

querystring = {"session_id":"1","project_id":"1","tag_ids":"3,4,5","media_type":"audio","language":"en"}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl --request GET \
  --url 'http://localhost:8888/api/2/assets/?session_id=1&project_id=1&tag_ids=3,4,5&media_type=audio&language=en' \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/assets/?session_id=1&project_id=1&tag_ids=3,4,5&media_type=audio&language=en",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

[
  {
    "id": 1,
    "description": "",
    "latitude": 1,
    "longitude": 1,
    "filename": "rw_test_audio1.wav",
    "file": null,
    "volume": 1,
    "submitted": true,
    "created": "2012-07-24T18:06:40",
    "weight": 50,
    "loc_caption": null,
    "project": 1,
    "language": "en",
    "loc_description": [],
    "loc_alt_text": [],
    "media_type": "audio",
    "audio_length_in_seconds": 30,
    "tag_ids": [8,3,5],
    "session_id": 1
  },
  {
    "id": 2,
    "description": "",
    "latitude": 1,
    "longitude": 1,
    "filename": "20170415-163557-1.wav",
    "file": "/rwmedia/20170415-163557-1.wav",
    "volume": 1,
    "submitted": true,
    "created": "2017-04-15T16:35:57.616822",
    "weight": 50,
    "loc_caption": null,
    "project": 1,
    "language": "en",
    "loc_description": [],
    "loc_alt_text": [],
    "media_type": "audio",
    "audio_length_in_seconds": 24.81,
    "tag_ids": [3,8],
    "session_id": 1
  }
]

Get list of Assets.

HTTP Request

GET localhost:8888/api/2/assets/

Optional Filters

Parameter Format Description/Notes
session_id integer
project_id integer
tag_ids comma separated list
media_type string audio, photo, text, video
language string 2-character language shortcode
envelope_id integer
longitude double
latitude double
submitted boolean determines whether or not asset will be available to streams etc
audiolength__lte double in seconds
audiolength__gte double in seconds
created__lte datetime
created__gte datetime

GET assets/:id/

import requests

url = "http://localhost:8888/api/2/assets/1/"

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/assets/1/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/assets/1/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 1,
  "description": "",
  "latitude": 1,
  "longitude": 1,
  "filename": "rw_test_audio1.wav",
  "file": null,
  "volume": 1,
  "submitted": true,
  "created": "2012-07-24T18:06:40",
  "weight": 50,
  "loc_caption": null,
  "project": 1,
  "language": "en",
  "loc_description": [],
  "loc_alt_text": [],
  "media_type": "audio",
  "audio_length_in_seconds": 30,
  "tag_ids": [8,3,5],
  "session_id": 1
}

Get specific Asset.

HTTP Request

GET localhost:8888/api/2/assets/1/

POST assets/

import requests

url = "http://localhost:8888/api/2/assets/"

payload = ""
headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/assets/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW'
var form = new FormData();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/assets/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "contentType": false,
  "mimeType": "multipart/form-data",
  "data": form
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 1,
  "description": "",
  "latitude": 1,
  "longitude": 1,
  "filename": "rw_test_audio1.wav",
  "file": null,
  "volume": 1,
  "submitted": true,
  "created": "2012-07-24T18:06:40",
  "weight": 50,
  "loc_caption": null,
  "project": 1,
  "language": "en",
  "loc_description": [47,48],
  "loc_alt_text": [49,50],
  "media_type": "audio",
  "audio_length_in_seconds": 30,
  "tag_ids": [8,3,5],
  "session_id": 1
}

Create new Asset.

If asset_id param is set, replace existing asset.

HTTP Request

POST localhost:8888/api/2/assets/

Required Parameters

Parameter Format Sample Description/Notes
session_id integer (required) 1
file mp3, wav, jpeg, png, txt basic mimetype checking done by server on upload
mediatype audio, photo, text, video audio defaults to audio

Optional Parameters

Parameter Format Sample Description/Notes
asset_id integer 1 only required to replace existing asset
description string this is a transcript of the audio or other useful info
latitude double 1.12345 defaults to project latitude
longitude double 2.34567 defaults to project longitude
submitted boolean true defaults to project.auto_submit value

GET assets/:id/votes/

import requests

url = "http://localhost:8888/api/2/assets/1/votes/"

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/assets/1/votes/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/assets/1/votes/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

[
  {
    "total": 1,
    "type": "rate",
    "avg": 5
  },
  {
    "total": 2,
    "type": "like"
  }
]

Get Votes associated with specific Asset, subtotaled by vote.vote_type.

HTTP Request

GET localhost:8888/api/2/assets/:id/votes/

POST assets/:id/votes/

import requests

url = "http://localhost:8888/api/2/assets/1/votes/"

payload = '{"session_id": 1, "vote_type": "rate", "value": 5}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/assets/1/votes/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "voter_id": 1,
  "session_id": 1,
  "vote_type": "rate",
  "value": 5
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/assets/1/votes/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"session_id": 1, "vote_type": "rate", "value": 5}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 8,
  "value": 5,
  "type": "rate",
  "voter_id": null,
  "asset_id": 1,
  "session_id": 1,
  "asset_votes": [
    {
      "total": 1,
      "type": "rate",
      "avg": 5
    },
    {
      "total": 2,
      "type": "like"
    }
  ]
}

Register Vote on specific Asset.

HTTP Request

POST localhost:8888/api/2/assets/:id/votes/

Required Parameters

Data format: application/json

Parameter Format Sample Description/Notes
session_id integer 1 must exist
vote_type string like OPTIONS: like, flag, rate, block_asset, block_user

Optional Parameters

Parameter Format Sample Description/Notes
value integer 4 mainly applies to vote_type = rate currently

audiotracks/

Definition:

A linear assemblage of alternating audio assets and silence (‘dead air’) which dynamically forms part of each stream by incorporating audio assets into the stream. There can be multiple audiotracks for each project which determine how many simultaneous audio assets can ever playback.

GET audiotracks/

import requests

url = "http://localhost:8888/api/2/audiotracks/"

querystring = {"project_id":"1","minduration__lte":"10","minduration__gte":"20","maxduration__lte":"30","maxduration__gte":"40"}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl --request GET \
  --url 'http://localhost:8888/api/2/audiotracks/?project_id=1&minduration__lte=10&minduration__gte=20&maxduration__lte=30&maxduration__gte=40' \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/audiotracks/?project_id=1&minduration__lte=10&minduration__gte=20&maxduration__lte=30&maxduration__gte=40",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

[
  {
    "id": 1,
    "minvolume": 1,
    "maxvolume": 1,
    "minduration": 5.5555,
    "maxduration": 10,
    "mindeadair": 1,
    "maxdeadair": 3,
    "minfadeintime": 0.1,
    "maxfadeintime": 0.5,
    "minfadeouttime": 0.1,
    "maxfadeouttime": 2,
    "minpanpos": 0,
    "maxpanpos": 0,
    "minpanduration": 5,
    "maxpanduration": 10,
    "repeatrecordings": false,
    "project_id": 1
  },
  {
    "id": 4,
    "minvolume": 0,
    "maxvolume": 1,
    "minduration": 2.5,
    "maxduration": 10,
    "mindeadair": 1,
    "maxdeadair": 3,
    "minfadeintime": 0.6,
    "maxfadeintime": 5,
    "minfadeouttime": 0.1,
    "maxfadeouttime": 2,
    "minpanpos": -0.5,
    "maxpanpos": 0.75,
    "minpanduration": 5,
    "maxpanduration": 17,
    "repeatrecordings": false,
    "project_id": 3
  }
]

Get list of Audiotracks.

HTTP Request

GET localhost:8888/api/2/audiotracks/

Optional Filters

Parameter Format Description/Notes
project_id integer
minduration__lte integer less than or equal to in seconds
minduration__gte integer greater than or equal to in seconds
maxduration__lte integer less than or equal to in seconds
maxduration__gte integer greater than or equal to in seconds
mindeadair__lte integer less than or equal to in seconds
mindeadair__gte integer greater than or equal to in seconds
maxdeadair__lte integer less than or equal to in seconds
maxdeadair__gte integer greater than or equal to in seconds

GET audiotracks/:id/

import requests

url = "http://localhost:8888/api/2/audiotracks/1/"

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/audiotracks/1/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/audiotracks/1/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 1,
  "minvolume": 1,
  "maxvolume": 1,
  "minduration": 5.5555,
  "maxduration": 10,
  "mindeadair": 1,
  "maxdeadair": 3,
  "minfadeintime": 0.1,
  "maxfadeintime": 0.5,
  "minfadeouttime": 0.1,
  "maxfadeouttime": 2,
  "minpanpos": 0,
  "maxpanpos": 0,
  "minpanduration": 5,
  "maxpanduration": 10,
  "repeatrecordings": false,
  "project_id": 1
}

Get specific Audiotrack.

HTTP Request

GET localhost:8888/api/2/audiotracks/1/

POST audiotracks/

import requests

url = "http://localhost:8888/api/2/audiotracks/"

payload = '{"project_id": 1,"minvolume": 0,"maxvolume": 1,"minduration": 2.5,"maxduration": 10,"mindeadair": 1,"maxdeadair": 3,"minfadeintime": 0.6,"maxfadeintime": 5,"minfadeouttime": 0.1,"maxfadeouttime": 2,"minpanpos": -0.5,"maxpanpos": 0.75,"minpanduration": 5,"maxpanduration": 17,"repeatrecordings": false}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/audiotracks/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "project_id": 1,
  "minvolume": 0,
  "maxvolume": 1,
  "minduration": 2.5,
  "maxduration": 10,
  "mindeadair": 1,
  "maxdeadair": 3,
  "minfadeintime": 0.6,
  "maxfadeintime": 5,
  "minfadeouttime": 0.1,
  "maxfadeouttime": 2,
  "minpanpos": -0.5,
  "maxpanpos": 0.75,
  "minpanduration": 5,
  "maxpanduration": 17,
  "repeatrecordings": false
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/audiotracks/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"project_id": 1,"minvolume": 0,"maxvolume": 1,"minduration": 2.5,"maxduration": 10,"mindeadair": 1,"maxdeadair": 3,"minfadeintime": 0.6,"maxfadeintime": 5,"minfadeouttime": 0.1,"maxfadeouttime": 2,"minpanpos": -0.5,"maxpanpos": 0.75,"minpanduration": 5,"maxpanduration": 17,"repeatrecordings": false}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 1,
  "description": "",
  "latitude": 1,
  "longitude": 1,
  "filename": "rw_test_audio1.wav",
  "file": null,
  "volume": 1,
  "submitted": true,
  "created": "2012-07-24T18:06:40",
  "weight": 50,
  "loc_caption": null,
  "project": 1,
  "language": "en",
  "loc_description": [47,48],
  "loc_alt_text": [49,50],
  "media_type": "audio",
  "audio_length_in_seconds": 30,
  "tag_ids": [8,3,5],
  "session_id": 1
}

Create new Audiotrack.

HTTP Request

POST localhost:8888/api/2/audiotracks/

Required Parameters

Data format: application/json

Parameter Format Sample Description/Notes
project_id integer 1
minvolume float 0.5
maxvolume float 1.0
minduration float 10
maxduration float 30
mindeadair float 5
maxdeadair float 10
minfadeintime float 1.5
maxfadeintime float 3.0
minfadeouttime float 1.0
maxfadeouttime float 2.5
minpanpos float -0.5 must be between -1.0 and 1.0
maxpanpos float 0.5 must be between -1.0 and 1.0
minpanduration float 10
maxpanduration float 20

Optional Parameters

Parameter Format Sample Description/Notes
repeatrecordings boolean true defaults to true

PATCH audiotracks/:id/

import requests

url = "http://localhost:8888/api/2/audiotracks/2/"

payload = '{"minvolume": 0.5,"maxvolume": 0.8}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("PATCH", url, data=payload, headers=headers)

print(response.text)
curl --request PATCH \
  --url http://localhost:8888/api/2/audiotracks/2/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "minvolume": 0,
  "maxvolume": 1,
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/audiotracks/2/",
  "method": "PATCH",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"minvolume": 0.5,"maxvolume": 0.8}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 2,
  "minvolume": 0.5,
  "maxvolume": 0.8,
  "minduration": 2.5,
  "maxduration": 10,
  "mindeadair": 1,
  "maxdeadair": 3,
  "minfadeintime": 0.6,
  "maxfadeintime": 5,
  "minfadeouttime": 0.1,
  "maxfadeouttime": 2,
  "minpanpos": -0.5,
  "maxpanpos": 0.75,
  "minpanduration": 5,
  "maxpanduration": 17,
  "repeatrecordings": false,
  "project_id": 1
}

Update Audiotrack.

HTTP Request

PATCH localhost:8888/api/2/audiotracks/:id/

Optional Parameters

Data format: application/json

Partial update allowed; params not included will leave field values unchanged.

Parameter Format Sample Description/Notes
project_id integer 1
minvolume float 0.5
maxvolume float 1.0
minduration float 10
maxduration float 30
mindeadair float 5
maxdeadair float 10
minfadeintime float 1.5
maxfadeintime float 3.0
minfadeouttime float 1.0
maxfadeouttime float 2.5
minpanpos float -0.5 must be between -1.0 and 1.0
maxpanpos float 0.5 must be between -1.0 and 1.0
minpanduration float 10
maxpanduration float 20
repeatrecordings boolean true defaults to true

DELETE audiotracks/:id/

import requests

url = "http://localhost:8888/api/2/audiotracks/3/"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("DELETE", url, data=payload, headers=headers)

print(response.text)
curl --request DELETE \
  --url http://localhost:8888/api/2/audiotracks/3/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/audiotracks/3/",
  "method": "DELETE",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "data": ""
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 204 No Content if successful

Delete Audiotrack

HTTP Request

DELETE localhost:8888/api/2/audiotracks/:id/

envelopes/

Definition:

A collection of assets submitted by a user/participant. Envelopes can contain multiple assets (several audio recordings, audio and photo, etc) collected at the same time by the same user. This is useful when there is a desire to bundle assets related to the same moment together, such as an audio recording with a photo of what was discussed in the recording.

POST envelopes/

import requests

url = "http://localhost:8888/api/2/envelopes/"

querystring = {"session_id":"1"}

payload = ""
headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("POST", url, data=payload, headers=headers, params=querystring)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/envelopes/ \
  --header 'authorization: token {{token}}' \
  --header 'content-type: application/json' \
  --data '{
  "session_id": 3
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/envelopes/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"session_id": 3}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "session_id": 3,
  "created": "2017-06-07T13:07:58.247988",
  "assets": [],
  "envelope_id": 5
}

Create new Envelope.

HTTP Request

POST localhost:8888/api/2/envelopes/

Required Parameters

Data format: application/json

Parameter Format Sample Description/Notes
session_id integer 1

PATCH envelopes/:id/

import requests

url = "http://localhost:8888/api/2/audiotracks/2/"

payload = '{"minvolume": 0.5,"maxvolume": 0.8}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("PATCH", url, data=payload, headers=headers)

print(response.text)
curl --request PATCH \
  --url http:///localhost:8888/api/2/envelopes/13/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW'
var form = new FormData();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/envelopes/13/",
  "method": "PATCH",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "contentType": false,
  "mimeType": "multipart/form-data",
  "data": form
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "description": "",
  "latitude": 1,
  "longitude": 1,
  "filename": "20170607-144505-1319.wav",
  "file": "/rwmedia/20170607-144505-1319.wav",
  "volume": 1,
  "submitted": true,
  "created": "2017-06-07T14:45:05.988692",
  "weight": 50,
  "loc_caption": null,
  "project": 2,
  "language": null,
  "loc_description": [],
  "loc_alt_text": [],
  "asset_id": 9991,
  "media_type": "audio",
  "audio_length_in_seconds": 11.76,
  "tag_ids": [3,5,4],
  "session_id": 1319
}

Update Envelope.

This is the preferred method for adding a new Asset to the system as this adds an Asset to the Envelope and creates the new Asset simultaneously.

HTTP Request

GET localhost:8888/api/2/envelopes/:id/

Optional Parameters

Data format: application/json

Partial update allowed; params not included will leave field values unchanged.

Parameter Format Sample Description/Notes
session_id integer 1
file binary new Asset created with file
latitude double 1.2345 assigned to newly created Asset
longitude double 2.3456 assigned to newly created Asset
tag_ids comma-separated list of integers 3,4,5 assigned to newly created Asset

events/

Definition:

A record of each time a client pings the server with an API call or internal server action occurs as a result of client activity. All events are tagged with an event_type such as start_session, start_listen, upload_recording, etc. Event data provides the core source for all RW system analysis.

GET events/

import requests

url = "http://localhost:8888/api/2/events/"

querystring = {"session_id":"1"}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl --request GET \
  --url 'http://localhost:8888/api/2/events/?session_id=1' \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/events/?session_id=1",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

[
  {
    "id": 1,
    "server_time": "2017-04-15T16:35:57.295461",
    "client_time": null,
    "event_type": "start_upload",
    "data": null,
    "latitude": null,
    "longitude": null,
    "session_id": 1,
    "tag_ids": "3,8"
  },
  {
    "id": 2,
    "server_time": "2017-04-15T16:36:04.916135",
    "client_time": null,
    "event_type": "start_upload",
    "data": null,
    "latitude": null,
    "longitude": null,
    "session_id": 1,
    "tag_ids": "4,8"
  }
]

Get list of Events.

HTTP Request

GET localhost:8888/api/2/events/

Optional Filters

Parameter Format Description/Notes
session_id integer
event_type string start_listen upload_recording etc
server_time datetime
server_time__gt datetime greater than specified datetime
server_time__lt datetime less than specified datetime
latitude double where event occurred
longitude double where event occurred
tag_ids list of integers certain event_types have tags associated with them

GET events/:id/

import requests

url = "http://localhost:8888/api/2/events/1/"

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/events/1/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/events/1/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 1,
  "server_time": "2017-05-06T22:55:15.114568",
  "client_time": null,
  "event_type": "start_upload",
  "data": null,
  "latitude": "40.75921249389648",
  "longitude": "-73.98463439941406",
  "session_id": 1,
  "tag_ids": "3,22,8"
}

Get specific Event.

HTTP Request

GET localhost:8888/api/2/events/1/

POST events/

import requests

url = "http://localhost:8888/api/2/events/"

payload = '{"session_id": 1, "event_type": "heartbeat", "client_time": "2017-05-06T22:55:15.114568", "latitude": 1.2345, "longitude": 2.3456, "tag_ids": "3,8", "data": "some random data"}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/events/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "session_id": 1,
  "event_type": "heartbeat",
  "client_time": "2017-05-06T22:55:15.114568",
  "latitude": 1.2345,
  "longitude": 2.3456,
  "tag_ids": "3,8",
  "data": "some random data"
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/events/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"session_id": 1, "event_type": "heartbeat", "client_time": "2017-05-06T22:55:15.114568", "latitude": 1.2345, "longitude": 2.3456, "tag_ids": "3,8", "data": "some random data"}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 10,
  "server_time": "2017-06-07T22:41:50.556694",
  "client_time": "2017-05-06T22:55:15.114568",
  "event_type": "heartbeat",
  "data": "some random data",
  "latitude": "1.2345",
  "longitude": "2.3456",
  "session_id": 1,
  "tag_ids": "3,8"
}

Create new Event.

HTTP Request

POST localhost:8888/api/2/events/

Required Parameters

Data format: application/json

Parameter Format Sample Description/Notes
session_id integer 1
event_type string 0.5 start_listen upload_recording etc

Optional Parameters

Parameter Format Sample Description/Notes
client_time boolean true defaults to true
latitude string will be changed to double in future release
longitude string will be changed to double in future release
tag_ids string 3,4,5
data string “some random data” whatever you want

languages/

Definition:

Roundware supports multiple languages. The ISO 2-character language code (i.e. en, fr, es etc) is used. Projects are assigned languages as part of their configuration and sessions are assigned languages based on that of the device initiating the session. Default is English en.

GET languages/

import requests

url = "http://localhost:8888/api/2/languages/"

querystring = {}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl --request GET \
  --url 'http://localhost:8888/api/2/languages/' \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/languages/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

[
  {
    "id": 2,
    "name": "Spanish",
    "language_code": "es"
  },
  {
    "id": 3,
    "name": "French",
    "language_code": "fr"
  },
  {
    "id": 1,
    "name": "English",
    "language_code": "en"
  }
]

Get list of Languages.

HTTP Request

GET localhost:8888/api/2/languages/

Optional Filters

Parameter Format Description/Notes
name string contains, case-insensitive
language_code string

GET languages/:id/

import requests

url = "http://localhost:8888/api/2/languages/2/"

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/languages/2/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/languages/2/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 2,
  "name": "Spanish",
  "language_code": "es"
}

Get specific Language.

HTTP Request

GET localhost:8888/api/2/languages/2/

POST languages/

import requests

url = "http://localhost:8888/api/2/languages/"

payload = '{"name": "French", "language_code": "fr"}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/languages/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "name": "French",
  "language_code": "fr",
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/languages/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"name": "French", "language_code": "fr"}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 3,
  "name": "French",
  "language_code": "fr"
}

Create new Language.

HTTP Request

POST localhost:8888/api/2/languages/

Required Parameters

Data format: application/json

Parameter Format Sample Description/Notes
language_code string fr Validates to 2-characters and non-existing

Optional Parameters

Parameter Format Sample Description/Notes
name string French used only for display purposes

PATCH languages/:id/

import requests

url = "http://localhost:8888/api/2/languages/3/"

payload = '{"name": "French!"}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("PATCH", url, data=payload, headers=headers)

print(response.text)
curl --request PATCH \
  --url http://localhost:8888/api/2/languages/3/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{"name": "French!"}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/languages/3/",
  "method": "PATCH",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"name": "French!"}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 3,
  "name": "French!",
  "language_code": "fr"
}

Update Language.

HTTP Request

PATCH localhost:8888/api/2/languages/:id/

Optional Parameters

Data format: application/json

Partial update allowed; params not included will leave field values unchanged.

Parameter Format Sample Description/Notes
language_code string fr Validates to 2-characters and non-existing
name string French used only for display purposes

DELETE languages/:id/

import requests

url = "http://localhost:8888/api/2/languages/3/"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("DELETE", url, data=payload, headers=headers)

print(response.text)
curl --request DELETE \
  --url http://localhost:8888/api/2/languages/3/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/languages/3/",
  "method": "DELETE",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "data": ""
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 204 No Content if successful

Delete Language

HTTP Request

DELETE localhost:8888/api/2/languages/:id/

listenevents/

Definition:

Listen events are essentially database logs of each asset that has played in the audio stream for each session. Information on the asset as well as the sequence is included such that sessions can be reconstructed after the fact for debugging and analysis.

GET listenevents/

import requests

url = "http://localhost:8888/api/2/listenevents/"

querystring = {"session":"35", "asset":"11"}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl --request GET \
  --url 'http://localhost:8888/api/2/listenevents/?session=35&asset=11' \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/listenevents/?session=35&asset=11",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

[
  {
    "id": 39,
    "duration_in_seconds": 28.41,
    "start_time": "2017-04-21T14:57:05.979645",
    "session_id": 35,
    "asset_id": 11
  },
  {
    "id": 41,
    "duration_in_seconds": 10.36,
    "start_time": "2017-04-21T14:58:55.979936",
    "session_id": 35,
    "asset_id": 11
  }
]

Get list of Listen Events.

HTTP Request

GET localhost:8888/api/2/listenevents/

Optional Filters

Parameter Format Description/Notes
session integer
asset integer
duration__lte integer currently in nanoseconds
duration__gte integer currently in nanoseconds
start_time__lte datetime format: 2017-04-21T14:58:55.979936
start_time__gte datetime format: 2017-04-21T14:58:55.979936

GET listenevents/:id/

import requests

url = "http://localhost:8888/api/2/listenevents/2/"

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/listenevents/2/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/listenevents/2/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 2,
  "duration_in_seconds": 10.36,
  "start_time": "2017-04-21T14:58:55.979936",
  "session_id": 35,
  "asset_id": 11
}

Get specific Listen Event.

HTTP Request

GET localhost:8888/api/2/listenevents/2/

localizedstrings/

Definition:

A string and corresponding language. Roundware supports multiple languages by assigning strings for each language to all text that requires localization.

GET localizedstrings/

import requests

url = "http://localhost:8888/api/2/localizedstrings/"

querystring = {"localized_string":"roundware","language":"en"}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl --request GET \
  --url 'http://localhost:8888/api/2/localizedstrings/?localized_string=roundware&language=en' \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/localizedstrings/?localized_string=roundware&language=en",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

[
  {
    "id": 2,
    "language": "en",
    "text": "Why are you using Roundware?"
  },
  {
    "id": 47,
    "language": "en",
    "text": "You are out of range of this Roundware project.  Please go somewhere within range and try again.  Thank you."
  }
]

Get list of Localized Strings.

HTTP Request

GET localhost:8888/api/2/localizedstrings/

Optional Filters

Parameter Format Description/Notes
language string contains, case-insensitive
localized_string string contains, case-insensitive

GET localizedstrings/:id/

import requests

url = "http://localhost:8888/api/2/localizedstrings/2/"

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/localizedstrings/2/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/localizedstrings/2/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 2,
  "language": "en",
  "text": "Why are you using Roundware?"
}

Get specific Localized String.

HTTP Request

GET localhost:8888/api/2/localizedstrings/2/

POST localizedstrings/

import requests

url = "http://localhost:8888/api/2/localizedstrings/"

payload = '{"localized_string":"This is a new localized string.", "language":"en"}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/localizedstrings/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "localized_string": "This is a new localized string.",
  "language": "en",
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/localizedstrings/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"localized_string":"This is a new localized string.", "language":"en"}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 3,
  "language": "en",
  "text": "This is a new localized string."
}

Create new Localized String.

HTTP Request

POST localhost:8888/api/2/localizedstrings/

Required Parameters

Data format: application/json

Parameter Format Sample Description/Notes
localized_string string Hello
language string en Validates to existing

PATCH languages/:id/

import requests

url = "http://localhost:8888/api/2/localizedstrings/3/"

payload = '{"localized_string":"This is an updated localized string."}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("PATCH", url, data=payload, headers=headers)

print(response.text)
curl --request PATCH \
  --url http://localhost:8888/api/2/localizedstrings/3/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{"localized_string":"This is an updated localized string."}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/localizedstrings/3/",
  "method": "PATCH",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"localized_string":"This is an updated localized string."}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 3,
  "language": "en",
  "text": "This is an updated localized string."
}

Update Localized String.

HTTP Request

PATCH localhost:8888/api/2/localizedstrings/:id/

Optional Parameters

Data format: application/json

Partial update allowed; params not included will leave field values unchanged.

Parameter Format Sample Description/Notes
localized_string string Hello
language string en Validates to existing

DELETE localizedstrings/:id/

import requests

url = "http://localhost:8888/api/2/localizedstrings/3/"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("DELETE", url, data=payload, headers=headers)

print(response.text)
curl --request DELETE \
  --url http://localhost:8888/api/2/localizedstrings/3/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/localizedstrings/3/",
  "method": "DELETE",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "data": ""
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 204 No Content if successful

Delete Localized String

HTTP Request

DELETE localhost:8888/api/2/localizedstrings/:id/

projects/

Definition:

The highest level of segmentation/grouping for all RW data. One RW instance can run many projects simultaneously, governed by CPU, bandwidth and memory resources.

GET projects/

import requests

url = "http:///localhost:8888/api/2/projects/"

querystring = {"name":"test","listen_enabled":"true","geo_listen_enabled":"true"}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl --request GET \
  --url 'http://localhost:8888/api/2/projects/?name=test&listen_enabled=true&geo_listen_enabled=true' \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/projects/?name=test&listen_enabled=true&geo_listen_enabled=true",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

[
  {
    "id": 1,
    "name": "Test Project",
    "latitude": 1,
    "longitude": 1,
    "pub_date": "2011-12-06T16:06:32",
    "audio_format": "mp3",
    "auto_submit": true,
    "max_recording_length": 30,
    "listen_questions_dynamic": false,
    "speak_questions_dynamic": false,
    "sharing_url": "http://roundware.org/r/eid=[id]",
    "out_of_range_url": "http://scapesaudio.dyndns.org:8000/mg_outofrange.mp3",
    "recording_radius": 200000,
    "listen_enabled": true,
    "geo_listen_enabled": true,
    "speak_enabled": true,
    "geo_speak_enabled": true,
    "reset_tag_defaults_on_startup": true,
    "timed_asset_priority": true,
    "repeat_mode": "stop",
    "files_url": "http://halseyburgund.com/dev/rw-base/webview/rw.zip",
    "files_version": "1",
    "audio_stream_bitrate": "128",
    "ordering": "random",
    "demo_stream_enabled": false,
    "demo_stream_url": "http://scapesaudio.dyndns.org:8000/scapes1.mp3",
    "out_of_range_distance": 10000,
    "sharing_message": "Check out this awesome recording I made using Roundware!",
    "out_of_range_message": "You are out of range of this Roundware project.  Please go somewhere within range and try again.  Thank you.",
    "legal_agreement": "Herein should be the brief legal agreement that participants need to agree to in order to make and submit a recording to a Roundware project.",
    "demo_stream_message": "You are out of range of this Roundware project.  Please go somewhere within range and try again.  Thank you.",
    "language_ids": [1]
  }
]

Get list of Projects.

HTTP Request

GET localhost:8888/api/2/projects/

Optional Filters

Parameter Format Description/Notes
name string contains, case-insensitive
listen_enabled boolean can the Project generate audio streams?
geo_listen_enabled boolean is the audio stream filtered by location?
speak_enabled boolean can the Project capture Assets from users?
geo_speak_enabled boolean do Assets uploaded by users have a location?

GET projects/:id/

import requests

url = "http://localhost:8888/api/2/projects/1/"

querystring = {"session_id": "1"}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/projects/1/?session_id=1 \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/projects/1/?session_id=1",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 1,
  "name": "Test Project",
  "latitude": 1,
  "longitude": 1,
  "pub_date": "2011-12-06T16:06:32",
  "audio_format": "mp3",
  "auto_submit": true,
  "max_recording_length": 30,
  "listen_questions_dynamic": false,
  "speak_questions_dynamic": false,
  "sharing_url": "http://roundware.org/r/eid=[id]",
  "out_of_range_url": "http://scapesaudio.dyndns.org:8000/mg_outofrange.mp3",
  "recording_radius": 200000,
  "listen_enabled": true,
  "geo_listen_enabled": true,
  "speak_enabled": true,
  "geo_speak_enabled": true,
  "reset_tag_defaults_on_startup": true,
  "timed_asset_priority": true,
  "repeat_mode": "stop",
  "files_url": "http://halseyburgund.com/dev/rw-base/webview/rw.zip",
  "files_version": "1",
  "audio_stream_bitrate": "128",
  "ordering": "random",
  "demo_stream_enabled": false,
  "demo_stream_url": "http://scapesaudio.dyndns.org:8000/scapes1.mp3",
  "out_of_range_distance": 10000,
  "sharing_message": "Check out this awesome recording I made using Roundware!",
  "out_of_range_message": "You are out of range of this Roundware project. Please go somewhere within range and try again. Thank you.",
  "legal_agreement": "Herein should be the brief legal agreement that participants need to agree to in order to make and submit a recording to a Roundware project.",
  "demo_stream_message": "You are out of range of this Roundware project. Please go somewhere within range and try again.  Thank you.",
  "language_ids": [1]
}

Get specific Project.

HTTP Request

GET localhost:8888/api/2/projects/1/?session_id=1

Required Parameters

Parameter Format Sample Description/Notes
session_id integer 1 this parameter is required to provide localization in theory, but not working currently

GET projects/:id/assets/

import requests

url = "http://localhost:8888/api/2/projects/1/assets/"

querystring = {"session_id":"1","submitted":"true"}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/projects/1/assets/?session_id=1&submitted=true \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/projects/1/assets/?session_id=1&submitted=true",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

[
  {
    "id": 1,
    "description": "",
    "latitude": 1,
    "longitude": 1,
    "filename": "rw_test_audio1.wav",
    "file": null,
    "volume": 1,
    "submitted": true,
    "created": "2012-07-24T18:06:40",
    "weight": 50,
    "loc_caption": null,
    "project": 1,
    "language": "en",
    "loc_description": [],
    "loc_alt_text": [],
    "media_type": "audio",
    "audio_length_in_seconds": 30,
    "tag_ids": [8,3,5],
    "session_id": 1
  },
  {
    "id": 2,
    "description": "",
    "latitude": 1,
    "longitude": 1,
    "filename": "20170415-163557-1.wav",
    "file": "/rwmedia/20170415-163557-1.wav",
    "volume": 1,
    "submitted": true,
    "created": "2017-04-15T16:35:57.616822",
    "weight": 50,
    "loc_caption": null,
    "project": 1,
    "language": "en",
    "loc_description": [47],
    "loc_alt_text": [],
    "media_type": "audio",
    "audio_length_in_seconds": 24.81,
    "tag_ids": [3,8],
    "session_id": 1
  }
]

Get Assets associated with specific Project.

HTTP Request

GET localhost:8888/api/2/projects/1/assets/

Optional Filters

Parameter Format Description/Notes
session_id integer
tag_ids list of integers
media_type string OPTIONS: audio, photo, text, video
language string 2-character language code
envelope_id integer
latitude float
longitude float
submitted boolean
audiolength__lte float in seconds less than or equal
audiolength__gte float in seconds greater than or equal
created__lte datetime
created__gte datetime

GET projects/:id/tags/

import requests

url = "http://localhost:8888/api/2/projects/1/tags/"

querystring = {"description":"male"}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/projects/1/tags/?description=male \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/projects/1/tags/?description=male",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "tags": [
    {
      "id": 3,
      "value": "male",
      "description": "male",
      "data": "class=tag-one",
      "filter": "",
      "location": null,
      "project_id": 1,
      "tag_category_id": 3,
      "description_loc": null,
      "msg_loc": "male",
      "relationships": [
        {
          "id": 2,
          "tag_id": 3,
          "parent_id": null
        },
        {
          "id": 17,
          "tag_id": 3,
          "parent_id": null
        }
      ]
    },
    {
      "id": 4,
      "value": "female",
      "description": "female",
      "data": "class=tag-one",
      "filter": "",
      "location": null,
      "project_id": 1,
      "tag_category_id": 3,
      "description_loc": null,
      "msg_loc": "female",
      "relationships": [
        {
          "id": 1,
          "tag_id": 4,
          "parent_id": null
        }
      ]
    }
  ]
}

Get Tags associated with specific Project.

HTTP Request

GET localhost:8888/api/2/projects/1/tags/

Optional Filters

Parameter Format Description/Notes
description string contains, case-insensitive
data string contains, case-insensitive

GET projects/:id/uigroups/

import requests

url = "http:///localhost:8888/api/2/projects/1/uigroups/"

querystring = {"ui_mode":"listen","active":"true"}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/projects/1/uigroups/?ui_mode=listen&active=true \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/projects/1/uigroups/?ui_mode=listen&active=true",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "ui_groups": [
    {
      "id": 1,
      "name": "What genders do you want to listen to?",
      "ui_mode": "listen",
      "select": "min_one",
      "active": true,
      "index": 1,
      "header_text_loc": "What genders do you want to listen to?",
      "tag_category_id": 3,
      "project_id": 1,
      "ui_items": [
        {
          "id": 1,
          "index": 2,
          "default": true,
          "active": true,
          "ui_group_id": 1,
          "tag_id": 3,
          "parent_id": null
        },
        {
          "id": 2,
          "index": 1,
          "default": true,
          "active": true,
          "ui_group_id": 1,
          "tag_id": 4,
          "parent_id": null
        }
      ]
    },
    {
      "id": 7,
      "name": "Who do you want to hear?",
      "ui_mode": "listen",
      "select": "min_one",
      "active": true,
      "index": 2,
      "header_text_loc": "Who do you want to hear?",
      "tag_category_id": 4,
      "project_id": 1,
      "ui_items": [
        {
          "id": 15,
          "index": 1,
          "default": true,
          "active": true,
          "ui_group_id": 7,
          "tag_id": 8,
          "parent_id": null
        },
        {
          "id": 16,
          "index": 2,
          "default": true,
          "active": true,
          "ui_group_id": 7,
          "tag_id": 9,
          "parent_id": null
        }
      ]
    }
  ]
}

Get UIGroups associated with specific Project.

HTTP Request

GET localhost:8888/api/2/projects/1/uigroups/

Optional Filters

Parameter Format Description/Notes
name string
ui_mode string OPTIONS: listen, speak, browse
tag_category_id integer
select string OPTIONS: single, multi, min_one
active boolean
index integer

POST projects/

import requests

url = "http://localhost:8888/api/2/projects/"

payload = '{"name":"New Project","latitude": 40,"longitude": -80,"pub_date":"2015-01-01T00:00:00","audio_format":"mp3","auto_submit": true,"max_recording_length": 35,"listen_questions_dynamic": false,"speak_questions_dynamic": false,"sharing_url": "http://roundware.org/r/eid=[id]","out_of_range_url": "http://roundware.dyndns.org:8000/outofrange.mp3","recording_radius": 10,"listen_enabled": true,"geo_listen_enabled": false,"speak_enabled": true,"geo_speak_enabled": true,"reset_tag_defaults_on_startup": false,"timed_asset_priority": false,"repeat_mode": "continuous","files_url": "http://roundware.dyndns.org/rw.zip","files_version": "1","audio_stream_bitrate": "128","ordering": "random","demo_stream_enabled": false,"demo_stream_url": "http://roundware.dyndns.org:8000/stream.mp3","out_of_range_distance": 5000,"language_ids": [1,2],"sharing_message_loc": [49,50],"out_of_range_message_loc": [47,48],"legal_agreement_loc": [53,54],"demo_stream_message_loc": [47,48]}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http:///localhost:8888/api/2/projects/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "name": "New Project",
  "latitude": 40,
  "longitude": -80,
  "pub_date": "2015-01-01T00:00:00",
  "audio_format": "mp3",
  "auto_submit": true,
  "max_recording_length": 35,
  "listen_questions_dynamic": false,
  "speak_questions_dynamic": false,
  "sharing_url": "http://roundware.org/r/eid=[id]",
  "out_of_range_url": "http://roundware.dyndns.org:8000/mg_outofrange.mp3",
  "recording_radius": 10,
  "listen_enabled": true,
  "geo_listen_enabled": false,
  "speak_enabled": true,
  "geo_speak_enabled": true,
  "reset_tag_defaults_on_startup": false,
  "timed_asset_priority": false,
  "repeat_mode": "continuous",
  "files_url": "http://halseyburgund.com/dev/rw-base/webview/rw.zip",
  "files_version": "1",
  "audio_stream_bitrate": "128",
  "ordering": "random",
  "demo_stream_enabled": false,
  "demo_stream_url": "http://roundware.dyndns.org:8000/scapes1.mp3",
  "out_of_range_distance": 5000,
  "language_ids": [1,2],
  "sharing_message_loc": [49,50],
  "out_of_range_message_loc": [47,48],
  "legal_agreement_loc": [53,54],
  "demo_stream_message_loc": [47,48]
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/projects/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"name":"New Project","latitude": 40,"longitude": -80,"pub_date":"2015-01-01T00:00:00","audio_format":"mp3","auto_submit": true,"max_recording_length": 35,"listen_questions_dynamic": false,"speak_questions_dynamic": false,"sharing_url": "http://roundware.org/r/eid=[id]","out_of_range_url": "http://roundware.dyndns.org:8000/outofrange.mp3","recording_radius": 10,"listen_enabled": true,"geo_listen_enabled": false,"speak_enabled": true,"geo_speak_enabled": true,"reset_tag_defaults_on_startup": false,"timed_asset_priority": false,"repeat_mode": "continuous","files_url": "http://roundware.dyndns.org/rw.zip","files_version": "1","audio_stream_bitrate": "128","ordering": "random","demo_stream_enabled": false,"demo_stream_url": "http://roundware.dyndns.org:8000/stream.mp3","out_of_range_distance": 5000,"language_ids": [1,2],"sharing_message_loc": [49,50],"out_of_range_message_loc": [47,48],"legal_agreement_loc": [53,54],"demo_stream_message_loc": [47,48]}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 9,
  "name": "New Project",
  "latitude": 40,
  "longitude": -80,
  "pub_date": "2015-01-01T00:00:00",
  "audio_format": "mp3",
  "auto_submit": true,
  "max_recording_length": 35,
  "listen_questions_dynamic": false,
  "speak_questions_dynamic": false,
  "sharing_url": "http://roundware.org/r/eid=[id]",
  "out_of_range_url": "http://roundware.dyndns.org:8000/outofrange.mp3",
  "recording_radius": 10,
  "listen_enabled": true,
  "geo_listen_enabled": false,
  "speak_enabled": true,
  "geo_speak_enabled": true,
  "reset_tag_defaults_on_startup": false,
  "timed_asset_priority": false,
  "repeat_mode": "continuous",
  "files_url": "http://roundware.dyndns.org/rw.zip",
  "files_version": "1",
  "audio_stream_bitrate": "128",
  "ordering": "random",
  "demo_stream_enabled": false,
  "demo_stream_url": "http://roundware.dyndns.org:8000/stream.mp3",
  "out_of_range_distance": 5000,
  "sharing_message": "Check out this awesome recording I made using Roundware!",
  "out_of_range_message": "You are out of range of this Roundware project.  Please go somewhere within range and try again.  Thank you.",
  "legal_agreement": "Herein should be the brief legal agreement that participants need to agree to in order to make and submit a recording to a Roundware project.",
  "demo_stream_message": "You are out of range of this Roundware project.  Please go somewhere within range and try again.  Thank you.",
  "language_ids": [2,1]
}

Create new Project.

HTTP Request

POST localhost:8888/api/2/projects/

Required Parameters

Data format: application/json

Parameter Format Sample Description/Notes
name string New Project
latitude float 1.234 “central” location for Project
longitude float 2.345 “central” location for Project
pub_date datetime 2015-01-01T00:00:00 auto-generated
audio_format string mp3 always mp3 for now
max_recording_length integer 30 max time users can speak
sharing_url string http://roundware.org/sharing.html url of web sharing page
out_of_range_url string http://roundware.org/outofrange.mp3 default static stream that plays when listener is out of range upon opening client
recording_radius integer 5 radius in meters of active range each Asset in Project will have as default
repeat_mode string stop OPTIONS: continuous, stop
audio_stream_bitrate varchar 128 bitrate of audio streams generated by Project
ordering string random OPTIONS: random, by_like, by_weight
out_of_range_distance float 100.5 distance in meters outside of Project Speaker ranges beyond which listener is considered out of range
language_ids list of language_ids 1,2 Projects can have multiple Languages assigned to them

Optional Parameters

Parameter Format Sample Description/Notes
auto_submit boolean true will Project Assets by default be immediately available to streams?
listen_enabled boolean true can the Project generate audio streams?
geo_listen_enabled boolean true is the audio stream filtered by location?
speak_enabled boolean true can the Project capture Assets from users?
geo_speak_enabled boolean true do Assets uploaded by users have a location?
reset_tag_defaults_on_startup boolean true
timed_asset_priority boolean true will timed Assets take priority over location Assets in playlist?
demo_stream_enabled boolean false should Project default all listeners to demo stream?
demo_stream_url string http://roundware.org/demo.mp3
files_url string http://roundware.dyndns.org/rw.zip zip file containing webview files for iOS and Android clients (to be deprecated)
files_version integer 1
sharing_message_loc list of localized_string_ids 5,6 default text for sharing message
out_of_range_message_loc list of localized_string_ids 7,8 listener is out of range notification text
legal_agreement_loc list of localized_string_ids 9,10 legal agreement text for contributions
demo_stream_message_loc list of localized_string_ids 11,12 notification text when demo stream is playing instead of dynamic stream
listen_questions_dynamic boolean false not currently used
speak_questions_dynamic boolean false not currently used

PATCH projects/:id/

import requests

url = "http://localhost:8888/api/2/projects/3/"

payload = '{"name":"Renamed Project"}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("PATCH", url, data=payload, headers=headers)

print(response.text)
curl --request PATCH \
  --url http://localhost:8888/api/2/projects/3/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{"name":"Renamed Project"}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/projects/3/",
  "method": "PATCH",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"name":"Renamed Project"}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 9,
  "name": "Renamed Project",
  "latitude": 40,
  "longitude": -80,
  "pub_date": "2015-01-01T00:00:00",
  "audio_format": "mp3",
  "auto_submit": true,
  "max_recording_length": 35,
  "listen_questions_dynamic": false,
  "speak_questions_dynamic": false,
  "sharing_url": "http://roundware.org/r/eid=[id]",
  "out_of_range_url": "http://roundware.dyndns.org:8000/outofrange.mp3",
  "recording_radius": 10,
  "listen_enabled": true,
  "geo_listen_enabled": false,
  "speak_enabled": true,
  "geo_speak_enabled": true,
  "reset_tag_defaults_on_startup": false,
  "timed_asset_priority": false,
  "repeat_mode": "continuous",
  "files_url": "http://roundware.dyndns.org/rw.zip",
  "files_version": "1",
  "audio_stream_bitrate": "128",
  "ordering": "random",
  "demo_stream_enabled": false,
  "demo_stream_url": "http://roundware.dyndns.org:8000/stream.mp3",
  "out_of_range_distance": 5000,
  "sharing_message": "Check out this awesome recording I made using Roundware!",
  "out_of_range_message": "You are out of range of this Roundware project.  Please go somewhere within range and try again.  Thank you.",
  "legal_agreement": "Herein should be the brief legal agreement that participants need to agree to in order to make and submit a recording to a Roundware project.",
  "demo_stream_message": "You are out of range of this Roundware project.  Please go somewhere within range and try again.  Thank you.",
  "language_ids": [2,1]
}

Update Project.

HTTP Request

PATCH localhost:8888/api/2/projects/:id/

Optional Parameters

Data format: application/json

Partial update allowed; params not included will leave field values unchanged.

Parameter Format Sample Description/Notes
name string New Project
latitude float 1.234 “central” location for Project
longitude float 2.345 “central” location for Project
pub_date datetime 2015-01-01T00:00:00 auto-generated
audio_format string mp3 always mp3 for now
max_recording_length integer 30 max time users can speak
sharing_url string http://roundware.org/sharing.html url of web sharing page
out_of_range_url string http://roundware.org/outofrange.mp3 default static stream that plays when listener is out of range upon opening client
recording_radius integer 5 radius in meters of active range each Asset in Project will have as default
repeat_mode string stop OPTIONS: continuous, stop
audio_stream_bitrate varchar 128 bitrate of audio streams generated by Project
ordering string random OPTIONS: random, by_like, by_weight
out_of_range_distance float 100.5 distance in meters outside of Project Speaker ranges beyond which listener is considered out of range
language_ids list of language_ids 1,2 Projects can have multiple Languages assigned to them
auto_submit boolean true will Project Assets by default be immediately available to streams?
listen_enabled boolean true can the Project generate audio streams?
geo_listen_enabled boolean true is the audio stream filtered by location?
speak_enabled boolean true can the Project capture Assets from users?
geo_speak_enabled boolean true do Assets uploaded by users have a location?
reset_tag_defaults_on_startup boolean true
timed_asset_priority boolean true will timed Assets take priority over location Assets in playlist?
demo_stream_enabled boolean false should Project default all listeners to demo stream?
demo_stream_url string http://roundware.org/demo.mp3
files_url string http://roundware.dyndns.org/rw.zip zip file containing webview files for iOS and Android clients (to be deprecated)
files_version integer 1
sharing_message_loc list of localized_string_ids 5,6 default text for sharing message
out_of_range_message_loc list of localized_string_ids 7,8 listener is out of range notification text
legal_agreement_loc list of localized_string_ids 9,10 legal agreement text for contributions
demo_stream_message_loc list of localized_string_ids 11,12 notification text when demo stream is playing instead of dynamic stream
listen_questions_dynamic boolean false not currently used
speak_questions_dynamic boolean false not currently used

DELETE projects/:id/

import requests

url = "http://localhost:8888/api/2/projects/3/"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("DELETE", url, data=payload, headers=headers)

print(response.text)
curl --request DELETE \
  --url http://localhost:8888/api/2/projects/3/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/projects/3/",
  "method": "DELETE",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "data": ""
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 204 No Content if successful

Delete Project

HTTP Request

DELETE localhost:8888/api/2/projects/:id/

sessions/

Definition:

A client server connection established when the client is started and terminated when the client app is closed. session_id is established by the server and is used to keep track of multiple simultaneous sessions.

POST sessions/

import requests

url = "http://localhost:8888/api/2/sessions/"

payload = '{"project_id": 1,"client_system": "iOS 8.1","geo_listen_enabled": true,"demo_stream_enabled": false,"language": "fr","timezone": "-8000"}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/sessions/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "project_id": 1,
  "client_system": "iOS 8.1",
  "geo_listen_enabled": true,
  "demo_stream_enabled": false,
  "language": "fr",
  "timezone": "-8000"
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/sessions/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"project_id": 1,"client_system": "iOS 8.1","geo_listen_enabled": true,"demo_stream_enabled": false,"language": "fr","timezone": "-8000"}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "client_system": "iOS 8.1",
  "client_type": "iPhone",
  "demo_stream_enabled": false,
  "device_id": "12891038109281",
  "geo_listen_enabled": true,
  "language": "fr",
  "project_id": 1,
  "starttime": "2017-06-09T02:42:03.939255",
  "stoptime": null,
  "timezone": "0000",
  "session_id": 104
}

Create new Session.

HTTP Request

POST localhost:8888/api/2/sessions/

Required Parameters

Data format: application/json

Parameter Format Sample Description/Notes
project_id integer 1
client_system string iOS 10.2

Optional Parameters

Parameter Format Sample Description/Notes
demo_stream_enabled boolean false defaults to false
geo_listen_enabled boolean true defaults to project.geo_listen_enabled
language 2-character code es defaults to en
timezone string “-5000” ISO timezone standard

speakers/

Definition:

A polygonal geographic zone within which a specific audio track or stream “broadcasts” continuously to listeners. Speakers can overlap, causing their audio to be mixed together accordingly. Volume attenuation happens linearly over a specified distance from the edge of the Speaker’s defined zone.

GET speakers/

import requests

url = "http://localhost:8888/api/2/speakers/"

querystring = {"project_id":"1","activeyn":"true"}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl --request GET \
  --url 'http://localhost:8888/api/2/speakers/?project_id=1&activeyn=true' \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/speakers/?project_id=1&activeyn=true",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

[
  {
    "id": 1,
    "activeyn": true,
    "code": "new",
    "maxvolume": 0.4,
    "minvolume": 0,
    "uri": "http://roundware.org:8000/scapes1.mp3",
    "backupuri": "http://roundware.org:8000/scapes3.mp3",
    "shape": {
      "type": "MultiPolygon",
      "coordinates": [
        [
          [
            [0,0],
            [0,10],
            [10,10],
            [10,0],
            [0,0]
          ]
        ]
      ]
    },
    "boundary": {
      "type": "MultiLineString",
      "coordinates": [
        [
          [0,0],
          [0,10],
          [10,10],
          [10,0],
          [0,0]
        ]
      ]
    },
    "attenuation_distance": 100,
    "attenuation_border": {
      "type": "LineString",
      "coordinates": [
        [ 0.0009131518699371853,0.0009205455301594167],
        [0.0009337239271925088,9.99912146712889],
        [9.99909287711822,9.999114357169784],
        [9.999113564532946,0.0009270542067677345],
        [0.0009131518699371853,0.0009205455301594167]
      ]
    },
    "project_id": 1
  }
]

Get list of Speakers.

HTTP Request

GET localhost:8888/api/2/speakers/

Optional Filters

Parameter Format Description/Notes
project_id integer
activeyn boolean

GET speakers/:id/

import requests

url = "http://localhost:8888/api/2/speakers/1/"

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/speakers/1/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/speakers/1/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 1,
  "activeyn": true,
  "code": "new",
  "maxvolume": 0.4,
  "minvolume": 0,
  "uri": "http://roundware.org:8000/scapes1.mp3",
  "backupuri": "http://roundware.org:8000/scapes3.mp3",
  "shape": {
    "type": "MultiPolygon",
    "coordinates": [
      [
        [
          [0,0],
          [0,10],
          [10,10],
          [10,0],
          [0,0]
        ]
      ]
    ]
  },
  "boundary": {
    "type": "MultiLineString",
    "coordinates": [
      [
        [0,0],
        [0,10],
        [10,10],
        [10,0],
        [0,0]
      ]
    ]
  },
  "attenuation_distance": 100,
  "attenuation_border": {
    "type": "LineString",
    "coordinates": [
      [ 0.0009131518699371853,0.0009205455301594167],
      [0.0009337239271925088,9.99912146712889],
      [9.99909287711822,9.999114357169784],
      [9.999113564532946,0.0009270542067677345],
      [0.0009131518699371853,0.0009205455301594167]
    ]
  },
  "project_id": 1
}

Get specific Speaker.

HTTP Request

GET localhost:8888/api/2/speakers/1/

POST speakers/

import requests

url = "http://localhost:8888/api/2/speakers/"

payload = '{"activeyn": true,"code": "new","maxvolume": 0.4,"minvolume": 0,"uri": "http://roundware.org:8000/scapes2.mp3","backupuri": "http://roundware.org:8000/scapes3.mp3","shape": {"type": "MultiPolygon","coordinates": [ [ [ [ 0, 0 ],[ 0, 10 ],[ 10, 10 ],[ 10, 0 ],[ 0, 0 ]] ] ]},"attenuation_distance": 100,"project_id": 1}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/speakers/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "activeyn": true,
  "code": "new",
  "maxvolume": 0.4,
  "minvolume": 0,
  "uri": "http://roundware.org:8000/scapes2.mp3",
  "backupuri": "http://roundware.org:8000/scapes3.mp3",
  "shape": {
    "type": "MultiPolygon",
    "coordinates": [
      [
        [
          [ 0, 0 ],
          [ 0, 10 ],
          [ 10, 10 ],
          [ 10, 0 ],
          [ 0, 0 ]
        ]
      ]
    ]
  },
  "attenuation_distance": 100,
  "project_id": 1
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/speakers/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"activeyn": true,"code": "new","maxvolume": 0.4,"minvolume": 0,"uri": "http://roundware.org:8000/scapes2.mp3","backupuri": "http://roundware.org:8000/scapes3.mp3","shape": {"type": "MultiPolygon","coordinates": [ [ [ [ 0, 0 ],[ 0, 10 ],[ 10, 10 ],[ 10, 0 ],[ 0, 0 ]] ] ]},"attenuation_distance": 100,"project_id": 1}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 2,
  "activeyn": true,
  "code": "new",
  "maxvolume": 0.4,
  "minvolume": 0,
  "uri": "http://roundware.org:8000/scapes1.mp3",
  "backupuri": "http://roundware.org:8000/scapes3.mp3",
  "shape": {
    "type": "MultiPolygon",
    "coordinates": [
      [
        [
          [0,0],
          [0,10],
          [10,10],
          [10,0],
          [0,0]
        ]
      ]
    ]
  },
  "boundary": {
    "type": "MultiLineString",
    "coordinates": [
      [
        [0,0],
        [0,10],
        [10,10],
        [10,0],
        [0,0]
      ]
    ]
  },
  "attenuation_distance": 100,
  "attenuation_border": {
    "type": "LineString",
    "coordinates": [
      [ 0.0009131518699371853,0.0009205455301594167],
      [0.0009337239271925088,9.99912146712889],
      [9.99909287711822,9.999114357169784],
      [9.999113564532946,0.0009270542067677345],
      [0.0009131518699371853,0.0009205455301594167]
    ]
  },
  "project_id": 1
}

Create new Speaker.

HTTP Request

POST localhost:8888/api/2/speakers/

Required Parameters

Data format: application/json

Parameter Format Sample Description/Notes
project_id integer 1
code string CENTER explanatory label
maxvolume float 0.5 volume of speaker audio when unattenuated in relation to source volume
minvolume float 0.0 volume of speaker audio when fully attenuated in relation to source volume
uri string http://my.site.com/audio.mp3 location of speaker audio source
backupuri string http://my.site.com/backup.mp3 if uri not available, this source will be used
shape MultiPolygon see sample code must be closed shape, but can contain as many points as necessary
attenuation_distance integer 100 in meters

Optional Parameters

Parameter Format Sample Description/Notes
activeyn boolean true defaults to false

PATCH speakers/:id/

import requests

url = "http://localhost:8888/api/2/speakers/2/"

payload = '{"maxvolume": 0.8}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("PATCH", url, data=payload, headers=headers)

print(response.text)
curl --request PATCH \
  --url http://localhost:8888/api/2/speakers/2/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "maxvolume": 0.8
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/speakers/2/",
  "method": "PATCH",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"maxvolume": 0.8}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 2,
  "activeyn": true,
  "code": "new",
  "maxvolume": 0.8,
  "minvolume": 0,
  "uri": "http://roundware.org:8000/scapes1.mp3",
  "backupuri": "http://roundware.org:8000/scapes3.mp3",
  "shape": {
    "type": "MultiPolygon",
    "coordinates": [
      [
        [
          [0,0],
          [0,10],
          [10,10],
          [10,0],
          [0,0]
        ]
      ]
    ]
  },
  "boundary": {
    "type": "MultiLineString",
    "coordinates": [
      [
        [0,0],
        [0,10],
        [10,10],
        [10,0],
        [0,0]
      ]
    ]
  },
  "attenuation_distance": 100,
  "attenuation_border": {
    "type": "LineString",
    "coordinates": [
      [ 0.0009131518699371853,0.0009205455301594167],
      [0.0009337239271925088,9.99912146712889],
      [9.99909287711822,9.999114357169784],
      [9.999113564532946,0.0009270542067677345],
      [0.0009131518699371853,0.0009205455301594167]
    ]
  },
  "project_id": 1
}

Update Speaker.

HTTP Request

PATCH localhost:8888/api/2/speakers/:id/

Optional Parameters

Data format: application/json

Partial update allowed; params not included will leave field values unchanged.

Parameter Format Sample Description/Notes
project_id integer 1
code string CENTER explanatory label
maxvolume float 0.5 volume of speaker audio when unattenuated in relation to source volume
minvolume float 0.0 volume of speaker audio when fully attenuated in relation to source volume
uri string http://my.site.com/audio.mp3 location of speaker audio source
backupuri string http://my.site.com/backup.mp3 if uri not available, this source will be used
shape MultiPolygon see sample code must be closed shape, but can contain as many points as necessary
attenuation_distance integer 100 in meters
activeyn boolean true defaults to false

DELETE speakers/:id/

import requests

url = "http://localhost:8888/api/2/speakers/3/"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("DELETE", url, data=payload, headers=headers)

print(response.text)
curl --request DELETE \
  --url http://localhost:8888/api/2/speakers/3/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/speakers/3/",
  "method": "DELETE",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "data": ""
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 204 No Content if successful

Delete Speaker

HTTP Request

DELETE localhost:8888/api/2/speakers/:id/

streams/

Definition:

A unique session-based audio stream generated by RW based on the evolving filters (tags and location) supplied by a particular client; streams consist of a summation of speaker audio and asset audio (per the audiotracks).

POST streams/

import requests

url = "http://localhost:8888/api/2/streams/"

payload = '{"session_id": 1, "latitude": 1.2345, "longitude": 2.3456}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/streams/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --data '{
  "session_id": 1,
  "latitude": 1.2345,
  "longitude": 2.3456
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/streams/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "data": '{"session_id": 1, "latitude": 1.2345, "longitude": 2.3456}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "stream_url": "http://localhost:8000/stream1.mp3",
  "stream_id": 1
}

Create new Stream.

HTTP Request

POST localhost:8888/api/2/streams/

Required Parameters

Data format: `multipart/form-data’

Parameter Format Sample Description/Notes
session_id integer 1 current client session

Optional Parameters

Parameter Format Sample Description/Notes
latitude double 1.2345 specifies initial location of listener; required for geo_listen_enabled=true sessions
longitude double 2.3456 specifies initial location of listener; required for geo_listen_enabled=true sessions

PATCH streams/:id/ [location]

import requests

url = "http://localhost:8888/api/2/streams/1/"

payload = '{"latitude": 2.3,"longitude": 1.2}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("PATCH", url, data=payload, headers=headers)

print(response.text)
curl --request PATCH \
  --url http://localhost:8888/api/2/streams/1/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --data '{
  "latitude": 0,
  "longitude": 1,
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/streams/1/",
  "method": "PATCH",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "data": '{"latitude": 1.21,"longitude": 3.24}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 200 OK if successful

Update Stream with new listener location.

HTTP Request

PATCH localhost:8888/api/2/streams/:id/

Required Parameters

Data format: multipart/form-data

Parameter Format Sample Description/Notes
latitude double 1.2345
longitude double 2.3456

PATCH streams/:id/ [tags]

import requests

url = "http://localhost:8888/api/2/streams/1/"

payload = '{"tag_ids": "3,4,5"}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("PATCH", url, data=payload, headers=headers)

print(response.text)
curl --request PATCH \
  --url http://localhost:8888/api/2/streams/1/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --data '{
  "tag_ids": "3,4,5"
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/streams/1/",
  "method": "PATCH",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "data": '{"tag_ids": "3,4,5"}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 200 OK if successful

Update Stream with new tag filters.

HTTP Request

PATCH localhost:8888/api/2/streams/:id/

Required Parameters

Data format: multipart/form-data

Parameter Format Sample Description/Notes
tag_ids comma separated list 3,4,5

POST streams/:id/heartbeat/

import requests

url = "http://localhost:8888/api/2/streams/1/heartbeat/"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http:///localhost:8888/api/2/streams/1/heartbeat/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/streams/1/heartbeat/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 200 OK if successful

Send heartbeat to Stream to register activity in order to keep alive.

HTTP Request

GET localhost:8888/api/2/streams/:id/heartbeat/

POST streams/:id/playasset/

import requests

url = "http://localhost:8888/api/2/streams/1/playasset/"

payload = '{"asset_id": 1}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http:///localhost:8888/api/2/streams/1/playasset/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW'
  --data '{
  "asset_id": 1
}'
var form = new FormData();
form.append('asset_id', 1);

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/streams/1/playasset/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "contentType": false,
  "mimeType": "multipart/form-data",
  "data": form
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 200 OK if successful

Fade out currently playing Asset in Stream and play specified Asset.

HTTP Request

GET localhost:8888/api/2/streams/:id/playasset/

POST streams/:id/replayasset/

import requests

url = "http://localhost:8888/api/2/streams/1/replayasset/"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http:///localhost:8888/api/2/streams/1/replayasset/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/streams/1/replayasset/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 200 OK if successful

Fade out currently playing Asset and play it again per Audiotrack settings.

HTTP Request

GET localhost:8888/api/2/streams/:id/replayasset/

POST streams/:id/skip/

import requests

url = "http://localhost:8888/api/2/streams/1/skip/"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http:///localhost:8888/api/2/streams/1/skip/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/streams/1/skip/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 200 OK if successful

Fade out currently playing Asset and play next Asset in playlist.

HTTP Request

GET localhost:8888/api/2/streams/:id/skip/

POST streams/:id/pause/

import requests

url = "http://localhost:8888/api/2/streams/1/pause/"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http:///localhost:8888/api/2/streams/1/pause/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/streams/1/pause/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 200 OK if successful

Fade out currently playing Asset and prevent new Assets from being added to the Stream from the playlist.

HTTP Request

GET localhost:8888/api/2/streams/:id/pause/

POST streams/:id/resume/

import requests

url = "http://localhost:8888/api/2/streams/1/resume/"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http:///localhost:8888/api/2/streams/1/resume/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/streams/1/resume/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 200 OK if successful

Undo pause action on Stream by resuming the adding of Assets to the Stream per Audiotrack settings.

HTTP Request

GET localhost:8888/api/2/streams/:id/resume/

GET streams/:id/isactive/

import requests

url = "http://localhost:8888/api/2/streams/1/isactive/"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/streams/1/isactive/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/streams/1/isactive/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "active": true,
  "stream_id": 1
}

Determine if a specific Stream is currently alive and streaming.

HTTP Request

GET localhost:8888/api/2/streams/:id/isactive/

tagcategories/

Definition:

Tag Categories are used to group Tags. For example, for Tag Category Age, the Tags might be Young and Old. Typically Tags of a specific Tag Category form the UI Items within a single UI Group.

GET tagcategories/

import requests

url = "http://localhost:8888/api/2/tagcategories/"

querystring = {}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl --request GET \
  --url 'http://localhost:8888/api/2/tagcategories/' \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/tagcategories/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

[
  {
    "id": 2,
    "name": "question",
    "data": ""
  },
  {
    "id": 3,
    "name": "gender",
    "data": ""
  },
  {
    "id": 4,
    "name": "usertype",
    "data": ""
  }
]

Get list of Tag Categories.

HTTP Request

GET localhost:8888/api/2/tagcategories/

Optional Filters

Parameter Format Description/Notes
name string contains and case-insensitive

GET tagcategories/:id/

import requests

url = "http://localhost:8888/api/2/tagcategories/2/"

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/tagcategories/2/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/tagcategories/2/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 2,
  "name": "question",
  "data": ""
}

Get specific Tag Category.

HTTP Request

GET localhost:8888/api/2/tagcategories/2/

POST tagcategories/

import requests

url = "http://localhost:8888/api/2/tagcategories/"

payload = '{"name": "new tag category", "data": "some useful further info"}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/tagcategories/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "name": "new tag category",
  "data": "some useful further info"
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/tagcategories/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"name": "new tag category", "data": "some useful further info"}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 5,
  "name": "new tag category",
  "data": "some useful further info"
}

Create new Tag Category.

HTTP Request

POST localhost:8888/api/2/tagcategories/

Required Parameters

Data format: application/json

Parameter Format Sample Description/Notes
name string new tag category

Optional Parameters

Parameter Format Sample Description/Notes
data string more info

PATCH tagcategories/:id/

import requests

url = "http://localhost:8888/api/2/tagcategories/5/"

payload = '{"name": "updated name"}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("PATCH", url, data=payload, headers=headers)

print(response.text)
curl --request PATCH \
  --url http://localhost:8888/api/2/tagcategories/5/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "name": "updated name"
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/tagcategories/5/",
  "method": "PATCH",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"name": "updated name"}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 5,
  "name": "updated name",
  "data": "some useful further info"
}

Update Tag Category.

HTTP Request

PATCH localhost:8888/api/2/tagcategories/:id/

Optional Parameters

Data format: application/json

Partial update allowed; params not included will leave field values unchanged.

Parameter Format Sample Description/Notes
name string new tag category
data string more info

DELETE tagcategories/:id/

import requests

url = "http://localhost:8888/api/2/tagcategories/5/"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("DELETE", url, data=payload, headers=headers)

print(response.text)
curl --request DELETE \
  --url http://localhost:8888/api/2/tagcategories/5/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/tagcategories/5/",
  "method": "DELETE",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "data": ""
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 204 No Content if successful

Delete Tag Category

HTTP Request

DELETE localhost:8888/api/2/tagcategories/:id/

tagrelationships/

Definition:

Tag Relationships define a hierarchy of Tags via parent-child relationships. This can be used to create useful filtering opportunities such as assigning an artist as parent of a painting which would allow filtering by the artist to include the painting.

GET tagrelationships/

import requests

url = "http://localhost:8888/api/2/tagrelationships/"

querystring = {"tag_id":"1"}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl --request GET \
  --url 'http://localhost:8888/api/2/tagrelationships/?tag_id=1' \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/tagrelationships/?tag_id=1",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

[
  {
    "id": 3,
    "tag_id": 8,
    "parent_id": 1
  },
  {
    "id": 6,
    "tag_id": 22,
    "parent_id": 1
  }
]

Get list of Tag Relationships.

HTTP Request

GET localhost:8888/api/2/tagrelationships/

Optional Filters

Parameter Format Description/Notes
tag_id integer
parent_id integer tag_id of parent tag

GET tagrelationships/:id/

import requests

url = "http://localhost:8888/api/2/tagrelationships/2/"

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/tagrelationships/2/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/tagrelationships/2/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 3,
  "tag_id": 8,
  "parent_id": 1
}

Get specific Tag Relationship.

HTTP Request

GET localhost:8888/api/2/tagrelationships/2/

POST tagrelationships/

import requests

url = "http://localhost:8888/api/2/tagrelationships/"

payload = '{"tag_id": 1, "parent_id": 5}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/tagrelationships/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "tag_id": 1,
  "parent_id": 5
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/tagrelationships/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"tag_id": 1, "parent_id": 5}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 3,
  "tag_id": 1,
  "parent_id": 5
}

Create new Tag Relationship.

HTTP Request

POST localhost:8888/api/2/tagrelationships/

Required Parameters

Data format: application/json

Parameter Format Sample Description/Notes
tag_id integer 1
parent_id integer 5

PATCH tagrelationships/:id/

import requests

url = "http://localhost:8888/api/2/tagrelationships/5/"

payload = '{"tag_id": 2, "parent_id": 8}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("PATCH", url, data=payload, headers=headers)

print(response.text)
curl --request PATCH \
  --url http://localhost:8888/api/2/tagrelationships/5/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "tag_id": 2,
  "parent_id": 8
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/tagrelationships/5/",
  "method": "PATCH",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"tag_id": 2, "parent_id": 8}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 5,
  "tag_id": 2,
  "parent_id": 8
}

Update Tag Relationship.

HTTP Request

PATCH localhost:8888/api/2/tagrelationships/:id/

Optional Parameters

Data format: application/json

Partial update allowed; params not included will leave field values unchanged.

Parameter Format Sample Description/Notes
tag_id integer 1
parent_id integer 5

DELETE tagrelationships/:id/

import requests

url = "http://localhost:8888/api/2/tagrelationships/5/"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("DELETE", url, data=payload, headers=headers)

print(response.text)
curl --request DELETE \
  --url http://localhost:8888/api/2/tagrelationships/5/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/tagrelationships/5/",
  "method": "DELETE",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "data": ""
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 204 No Content if successful

Delete Tag Relationship

HTTP Request

DELETE localhost:8888/api/2/tagrelationships/:id/

tags/

Definition:

Tags are metadata used to describe Assets. Tags are arranged by Tag Category. For example, the tags within the age Tag Category could be young and old. Tags are very flexible and allow for collecting many different types of metadata to be used for filtering the assets at a later time.

GET tags/

import requests

url = "http://localhost:8888/api/2/tags/"

querystring = {"description": "male"}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl --request GET \
  --url 'http://localhost:8888/api/2/tags/?description=male' \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/tags/?description=male",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "tags": [
    {
      "id": 3,
      "value": "male",
      "description": "male",
      "data": "class=tag-one",
      "filter": "",
      "location": null,
      "project_id": 1,
      "tag_category_id": 3,
      "description_loc": null,
      "msg_loc": "male",
      "relationships": [
        {
          "id": 2,
          "tag_id": 3,
          "parent_id": null
        },
        {
          "id": 17,
          "tag_id": 3,
          "parent_id": null
        }
      ]
    },
    {
      "id": 4,
      "value": "female",
      "description": "female",
      "data": "class=tag-one",
      "filter": "",
      "location": null,
      "project_id": 1,
      "tag_category_id": 3,
      "description_loc": null,
      "msg_loc": "female",
      "relationships": [
        {
          "id": 1,
          "tag_id": 4,
          "parent_id": null
        }
      ]
    }
  ]
}

Get list of Tags.

HTTP Request

GET localhost:8888/api/2/tags/

Optional Filters

Parameter Format Description/Notes
project_id integer
description string contains and case-insensitive
data string contains and case-insensitive

GET tags/:id/

import requests

url = "http://localhost:8888/api/2/tags/2/"

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/tags/2/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/tags/2/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 4,
  "value": "female",
  "description": "female",
  "data": "class=tag-one",
  "filter": "",
  "location": null,
  "project_id": 1,
  "tag_category_id": 3,
  "description_loc": null,
  "msg_loc": "female",
  "relationships": [
    {
      "id": 1,
      "tag_id": 4,
      "parent_id": null
    }
  ]
}

Get specific Tag.

HTTP Request

GET localhost:8888/api/2/tags/2/

POST tags/

import requests

url = "http://localhost:8888/api/2/tags/"

payload = '{"value": "male","description": "male","data": "class=tag-one","project_id": 1,"tag_category_id": 3,"description_loc_ids": [44,43], "msg_loc_ids": [5,6]}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/tags/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "value": "male",
  "description": "male",
  "data": "class=tag-one",
  "filter": "",
  "location": null,
  "project_id": 1,
  "tag_category_id": 3,
  "description_loc_ids": [44,43],
  "msg_loc_ids": [5,6]
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/tags/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"value": "male","description": "male","data": "class=tag-one","project_id": 1,"tag_category_id": 3,"description_loc_ids": [44,43], "msg_loc_ids": [5,6]}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 7,
  "value": "male",
  "description": "male",
  "data": "class=tag-one",
  "filter": "",
  "location": null,
  "project_id": 1,
  "tag_category_id": 3,
  "description_loc": [44,43],
  "msg_loc": "female",
  "relationships": []
}

Create new Tag.

HTTP Request

POST localhost:8888/api/2/tags/

Required Parameters

Data format: application/json

Parameter Format Sample Description/Notes
value string new tag category
project_id integer 1
tag_category_id integer 2

Optional Parameters

Parameter Format Sample Description/Notes
description string more info
description_loc_ids list of localized_string_ids 3,4
msg_loc_ids list of localized_string_ids 6,7
data string more data useful place to store additional tag info
filter enum _ten_most_recent_days untested functionality allows for pseudo tags to be created by filtering rather than directly assigning
location shape Tags will be filterable by location in the future, but aren’t yet

PATCH tags/:id/

import requests

url = "http://localhost:8888/api/2/tags/7/"

payload = '{"value": "male"}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("PATCH", url, data=payload, headers=headers)

print(response.text)
curl --request PATCH \
  --url http://localhost:8888/api/2/tags/7/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "value": "male"
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/tags/7/",
  "method": "PATCH",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"value": "male"}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 7,
  "value": "female",
  "description": "male",
  "data": "class=tag-one",
  "filter": "",
  "location": null,
  "project_id": 1,
  "tag_category_id": 3,
  "description_loc": [44,43],
  "msg_loc": "female",
  "relationships": []
}

Update Tag.

HTTP Request

PATCH localhost:8888/api/2/tags/:id/

Optional Parameters

Data format: application/json

Partial update allowed; params not included will leave field values unchanged.

Parameter Format Sample Description/Notes
value string new tag category
project_id integer 1
tag_category_id integer 2
description string more info
description_loc_ids list of localized_string_ids 3,4
msg_loc_ids list of localized_string_ids 6,7
data string more data useful place to store additional tag info
filter enum _ten_most_recent_days untested functionality allows for pseudo tags to be created by filtering rather than directly assigning
location shape Tags will be filterable by location in the future, but aren’t yet

DELETE tags/:id/

import requests

url = "http://localhost:8888/api/2/tags//"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("DELETE", url, data=payload, headers=headers)

print(response.text)
curl --request DELETE \
  --url http://localhost:8888/api/2/tags/5/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/tags/5/",
  "method": "DELETE",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "data": ""
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 204 No Content if successful

Delete Tag Category

HTTP Request

DELETE localhost:8888/api/2/tags/:id/

timedassets/

Definition:

Assets that are made available based on session length rather than location. This allows for a loose linear narrative to be imposed on top of the otherwise unpredictable experience based on the path that a user wanders.

GET timedassets/

import requests

url = "http://localhost:8888/api/2/timedassets/"

querystring = {"project_id": "1"}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl --request GET \
  --url 'http://localhost:8888/api/2/timedassets/?project_id=1' \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/timedassets/?project_id=1",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

[
  {
    "id": 1,
    "start": 50,
    "end": 100,
    "asset_id": 1,
    "project_id": 1
  },
  {
    "id": 3,
    "start": 55,
    "end": 100,
    "asset_id": 1,
    "project_id": 1
  },
  {
    "id": 5,
    "start": 50,
    "end": 100,
    "asset_id": 2,
    "project_id": 1
  }
]

Get list of Timed Assets.

HTTP Request

GET localhost:8888/api/2/timedassets/

Optional Filters

Parameter Format Description/Notes
project_id integer
start__gte integer in seconds, greater than or equal
start__lte integer in seconds, less than or equal
end__gte integer in seconds, greater than or equal
end__lte integer in seconds, less than or equal

GET timedassets/:id/

import requests

url = "http://localhost:8888/api/2/timedassets/2/"

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/timedassets/2/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/timedassets/2/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 2,
  "start": 55,
  "end": 100,
  "asset_id": 1,
  "project_id": 1
}

Get specific Timed Assets.

HTTP Request

GET localhost:8888/api/2/timedassets/2/

POST timedassets/

import requests

url = "http://localhost:8888/api/2/timedassets/"

payload = '{"start": 50,"end": 100,"asset_id" : 2,"project_id": 1}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/timedassets/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "start": 50,
  "end": 100,
  "asset_id" : 2,
  "project_id": 1
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/timedassets/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"start": 50,"end": 100,"asset_id" : 2,"project_id": 1}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 7,
  "start": 50,
  "end": 100,
  "asset_id": 2,
  "project_id": 1
}

Create new Timed Asset.

HTTP Request

POST localhost:8888/api/2/timedassets/

Required Parameters

Data format: application/json

Parameter Format Sample Description/Notes
project_id integer 1
asset_id integer 5
start integer 50 when Asset becomes available to playlist
end integer 100 when Asset becomes unavailable to playlist

PATCH timedassets/:id/

import requests

url = "http://localhost:8888/api/2/timedassets/7/"

payload = '{"start": 10}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("PATCH", url, data=payload, headers=headers)

print(response.text)
curl --request PATCH \
  --url http://localhost:8888/api/2/timedassets/7/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "start": 10
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/timedassets/7/",
  "method": "PATCH",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"start": 10}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 7,
  "start": 10,
  "end": 100,
  "asset_id": 2,
  "project_id": 1
}

Update Timed Asset.

HTTP Request

PATCH localhost:8888/api/2/timedassets/:id/

Optional Parameters

Data format: application/json

Partial update allowed; params not included will leave field values unchanged.

Parameter Format Sample Description/Notes
project_id integer 1
asset_id integer 5
start integer 50 when Asset becomes available to playlist
end integer 100 when Asset becomes unavailable to playlist

DELETE timedassets/:id/

import requests

url = "http://localhost:8888/api/2/timedassets/5/"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("DELETE", url, data=payload, headers=headers)

print(response.text)
curl --request DELETE \
  --url http://localhost:8888/api/2/timedassets/5/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/timedassets/5/",
  "method": "DELETE",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "data": ""
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 204 No Content if successful

Delete Timed Asset

HTTP Request

DELETE localhost:8888/api/2/timedassets/:id/

uigroups/

Definition:

UI Groups are used to group UI Items together in RW client user interfaces. UI Groups typically correspond to a Tag Category with UI Items corresponding to Tags within that Category.

GET uigroups/

import requests

url = "http://localhost:8888/api/2/uigroups/"

querystring = {"project_id": "1"}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl --request GET \
  --url 'http://localhost:8888/api/2/uigroups/?project_id=1' \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/uigroups/?project_id=1",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "ui_groups": [
    {
      "id": 1,
      "name": "What genders do you want to listen to?",
      "ui_mode": "listen",
      "select": "min_one",
      "active": true,
      "index": 1,
      "header_text_loc": "What genders do you want to listen to?",
      "tag_category_id": 3,
      "project_id": 1,
      "ui_items": [
        {
          "id": 1,
          "index": 2,
          "default": true,
          "active": true,
          "ui_group_id": 1,
          "tag_id": 3,
          "parent_id": null
        },
        {
          "id": 2,
          "index": 1,
          "default": true,
          "active": true,
          "ui_group_id": 1,
          "tag_id": 4,
          "parent_id": null
        }
      ]
    },
    {
      "id": 7,
      "name": "Who do you want to hear?",
      "ui_mode": "listen",
      "select": "min_one",
      "active": true,
      "index": 2,
      "header_text_loc": "Who do you want to hear?",
      "tag_category_id": 4,
      "project_id": 1,
      "ui_items": [
        {
          "id": 15,
          "index": 1,
          "default": true,
          "active": true,
          "ui_group_id": 7,
          "tag_id": 8,
          "parent_id": null
        },
        {
          "id": 16,
          "index": 2,
          "default": true,
          "active": true,
          "ui_group_id": 7,
          "tag_id": 9,
          "parent_id": null
        }
      ]
    }
  ]
}

Get list of UI Groups.

HTTP Request

GET localhost:8888/api/2/uigroups/

Optional Filters

Parameter Format Description/Notes
project_id integer
name string startswith filter
ui_mode enum OPTIONS: listen, speak, browse
tag_category_id integer
select enum OPTIONS: single, multi, min_one
active boolean
index integer imposes ordering in client UI

GET uigroups/:id/

import requests

url = "http://localhost:8888/api/2/uigroups/2/"

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/uigroups/2/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/uigroups/2/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 2,
  "name": "Who do you want to hear?",
  "ui_mode": "listen",
  "select": "min_one",
  "active": true,
  "index": 2,
  "header_text_loc": "Who do you want to hear?",
  "tag_category_id": 4,
  "project_id": 1,
  "ui_items": [
    {
      "id": 15,
      "index": 1,
      "default": true,
      "active": true,
      "ui_group_id": 2,
      "tag_id": 8,
      "parent_id": null
    },
    {
      "id": 16,
      "index": 2,
      "default": true,
      "active": true,
      "ui_group_id": 2,
      "tag_id": 9,
      "parent_id": null
    }
  ]
}

Get specific UI Group.

HTTP Request

GET localhost:8888/api/2/uigroups/2/

POST uigroups/

import requests

url = "http://localhost:8888/api/2/uigroups/"

payload = '{"name": "What genders do you want to listen to?"","ui_mode": "listen","select": "min_one","active": true,"index": 1,"header_text_loc_ids": [42,41],"tag_category_id": 3,"project_id": 1}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/uigroups/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
    "name": "What genders do you want to listen to?",
    "ui_mode": "listen",
    "select": "min_one",
    "active": true,
    "index": 1,
    "header_text_loc_ids": [42,41],
    "tag_category_id": 3,
    "project_id": 1
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/uigroups/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"name": "What genders do you want to listen to?"","ui_mode": "listen","select": "min_one","active": true,"index": 1,"header_text_loc_ids": [42,41],"tag_category_id": 3,"project_id": 1}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 15,
  "name": "What genders do you want to listen to?",
  "ui_mode": "listen",
  "select": "min_one",
  "active": true,
  "index": 1,
  "header_text_loc": "Leave feedback",
  "tag_category_id": 3,
  "project_id": 1,
  "ui_items": []
}

Create new UI Group.

HTTP Request

POST localhost:8888/api/2/uigroups/

Required Parameters

Data format: application/json

Parameter Format Sample Description/Notes
project_id integer 1
name string Name
ui_mode enum listen OPTIONS: listen, speak, browse
tag_category_id integer 2
select enum single OPTIONS: single, multi, min_one
index integer 1 imposes ordering in client UI

Optional Parameters

Parameter Format Sample Description/Notes
header_text_loc_ids list of integers 4,7
active boolean true defaults to true

PATCH uigroups/:id/

import requests

url = "http://localhost:8888/api/2/uigroups/15/"

payload = '{"ui_mode": "speak"}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("PATCH", url, data=payload, headers=headers)

print(response.text)
curl --request PATCH \
  --url http://localhost:8888/api/2/uigroups/15/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "ui_mode": "speak"
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/uigroups/15/",
  "method": "PATCH",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"ui_mode": "speak"}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 15,
  "name": "What genders do you want to listen to?",
  "ui_mode": "speak",
  "select": "min_one",
  "active": true,
  "index": 1,
  "header_text_loc": "Leave feedback",
  "tag_category_id": 3,
  "project_id": 1,
  "ui_items": []
}

Update UI Group.

HTTP Request

PATCH localhost:8888/api/2/uigroups/:id/

Optional Parameters

Data format: application/json

Partial update allowed; params not included will leave field values unchanged.

Parameter Format Sample Description/Notes
project_id integer 1
name string Name
ui_mode enum listen OPTIONS: listen, speak, browse
tag_category integer 2
select enum single OPTIONS: single, multi, min_one
index integer 1 imposes ordering in client UI
header_text_loc string Header text
active boolean true defaults to true

DELETE uigroups/:id/

import requests

url = "http://localhost:8888/api/2/uigroups/5/"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("DELETE", url, data=payload, headers=headers)

print(response.text)
curl --request DELETE \
  --url http://localhost:8888/api/2/uigroups/5/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/uigroups/5/",
  "method": "DELETE",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "data": ""
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 204 No Content if successful

Delete UI Group.

HTTP Request

DELETE localhost:8888/api/2/uigroups/:id/

uiitems/

Definition:

UI Items represent Tags in client user interfaces. UI Items are grouped into UI Groups in the user interface and are displayed together to allow for user selections.

GET uiitems/

import requests

url = "http://localhost:8888/api/2/uiitems/"

querystring = {"ui_group_id": "1","active":"true"}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl --request GET \
  --url 'http://localhost:8888/api/2/uiitems/?ui_group_id=3&active=true' \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/uiitems/?ui_group_id=3&active=true'",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

[
  {
    "id": 5,
    "index": 1,
    "default": true,
    "active": true,
    "ui_group_id": 3,
    "tag_id": 5,
    "parent_id": null
  },
  {
    "id": 54,
    "index": 2,
    "default": true,
    "active": true,
    "ui_group_id": 3,
    "tag_id": 22,
    "parent_id": null
  }
]

Get list of UI Items.

HTTP Request

GET localhost:8888/api/2/uiitems/

Optional Filters

Parameter Format Description/Notes
ui_group_id integer
tag_id integer
active boolean
parent_id integer
default boolean
index integer imposes ordering in client UI

GET uiitems/:id/

import requests

url = "http://localhost:8888/api/2/uiitems/2/"

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/uiitems/2/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/uiitems/2/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 2,
  "index": 2,
  "default": true,
  "active": true,
  "ui_group_id": 3,
  "tag_id": 22,
  "parent_id": null
}

Get specific UI Item.

HTTP Request

GET localhost:8888/api/2/uiitems/2/

POST uiitems/

import requests

url = "http://localhost:8888/api/2/uiitems/"

payload = '{"index": 2,"default": true,"active": true,"ui_group_id": 3,"tag_id": 8,"parent_id": null}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/uiitems/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
    "index": 2,
    "default": true,
    "active": true,
    "ui_group_id": 3,
    "tag_id": 8,
    "parent_id": null
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/uiitems/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"index": 2,"default": true,"active": true,"ui_group_id": 3,"tag_id": 8,"parent_id": null}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 61,
  "index": 2,
  "default": true,
  "active": true,
  "ui_group_id": 3,
  "tag_id": 8,
  "parent_id": null
}

Create new UI Item.

HTTP Request

POST localhost:8888/api/2/uiitems/

Required Parameters

Data format: application/json

Parameter Format Sample Description/Notes
ui_group_id integer 7
tag_id integer 9
parent_id integer 18
index integer 2 imposes ordering in client UI

Optional Parameters

Parameter Format Sample Description/Notes
default boolean true defaults to false
active boolean true defaults to false

PATCH uiitems/:id/

import requests

url = "http://localhost:8888/api/2/uiitems/15/"

payload = '{"active": "false"}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("PATCH", url, data=payload, headers=headers)

print(response.text)
curl --request PATCH \
  --url http://localhost:8888/api/2/uiitems/15/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "active": "false"
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/uiitems/15/",
  "method": "PATCH",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"active": "false"}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 61,
  "index": 2,
  "default": true,
  "active": false,
  "ui_group_id": 3,
  "tag_id": 8,
  "parent_id": null
}

Update UI Item.

HTTP Request

PATCH localhost:8888/api/2/uiitems/:id/

Optional Parameters

Data format: application/json

Partial update allowed; params not included will leave field values unchanged.

Parameter Format Sample Description/Notes
ui_group_id integer 7
tag_id integer 9
parent_id integer 18
index integer 2 imposes ordering in client UI
default boolean true defaults to false
active boolean true defaults to false

DELETE uiitems/:id/

import requests

url = "http://localhost:8888/api/2/uiitems/5/"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("DELETE", url, data=payload, headers=headers)

print(response.text)
curl --request DELETE \
  --url http://localhost:8888/api/2/uiitems/5/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/uiitems/5/",
  "method": "DELETE",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "data": ""
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 204 No Content if successful

Delete UI Item.

HTTP Request

DELETE localhost:8888/api/2/uiitems/:id/

votes/

Definition:

Votes provide a way for users to register their opinion with respect to particular Assets. There are certain Vote types (like, flag, etc) which can be exposed to users to allow them to cast.

GET votes/

import requests

url = "http://localhost:8888/api/2/votes/"

querystring = {"asset_id": "1"}

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
curl --request GET \
  --url 'http://localhost:8888/api/2/votes/?asset_id=1' \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/votes/?asset_id=1'",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

[
  {
    "id": 1,
    "value": 5,
    "type": "like",
    "voter_id": 1,
    "asset_id": 1,
    "session_id": 1,
    "asset_votes": [
      {
        "total": 1,
        "type": "rate",
        "avg": 5
      },
      {
        "total": 2,
        "type": "like"
      }
    ]
  },
  {
    "id": 2,
    "value": 3,
    "type": "like",
    "voter_id": 1,
    "asset_id": 1,
    "session_id": 2,
    "asset_votes": [
      {
        "total": 1,
        "type": "rate",
        "avg": 5
      },
      {
        "total": 2,
        "type": "like"
      }
    ]
  },
  {
    "id": 8,
    "value": 5,
    "type": "rate",
    "voter_id": null,
    "asset_id": 1,
    "session_id": 1,
    "asset_votes": [
      {
        "total": 1,
        "type": "rate",
        "avg": 5
      },
      {
        "total": 2,
        "type": "like"
      }
    ]
  }
]

Get list of Votes.

HTTP Request

GET localhost:8888/api/2/votes/

Optional Filters

Parameter Format Description/Notes
session_id integer
voter_id integer corresponds to user.id in database
asset_id integer
type enum OPTIONS: flag, like, rate, block_asset, block_user
value integer certain vote types require further info ie rate

GET votes/:id/

import requests

url = "http://localhost:8888/api/2/votes/2/"

headers = {'authorization': 'token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'}

response = requests.request("GET", url, headers=headers)

print(response.text)
curl --request GET \
  --url http://localhost:8888/api/2/votes/2/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/votes/2/",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 1,
  "value": 5,
  "type": "like",
  "voter_id": 1,
  "asset_id": 1,
  "session_id": 1,
  "asset_votes": [
    {
      "total": 1,
      "type": "rate",
      "avg": 5
    },
    {
      "total": 2,
      "type": "like"
    }
  ]
}

Get specific Vote.

HTTP Request

GET localhost:8888/api/2/votes/2/

POST votes/

import requests

url = "http://localhost:8888/api/2/votes/"

payload = '{"type": "rate","value": 5,"asset_id" : 3,"session_id": 1}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url http://localhost:8888/api/2/votes/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
    "type": "rate",
    "value": 5,
    "asset_id" : 3,
    "session_id": 1
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/votes/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"type": "rate","value": 5,"asset_id" : 3,"session_id": 1}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 10,
  "value": 5,
  "type": "rate",
  "voter_id": null,
  "asset_id": 3,
  "session_id": 1,
  "asset_votes": [
    {
      "total": 1,
      "type": "like"
    },
    {
      "total": 3,
      "type": "rate",
      "avg": 5
    }
  ]
}

Create new Vote.

HTTP Request

POST localhost:8888/api/2/votes/

Required Parameters

Data format: application/json

Parameter Format Sample Description/Notes
session_id integer 7
asset_id integer 9
type integer 18 OPTIONS: flag, like, rate, block_asset, block_user

Optional Parameters

Parameter Format Sample Description/Notes
value integer 3 only used with rate currently

PATCH votes/:id/

import requests

url = "http://localhost:8888/api/2/votes/15/"

payload = '{"value": "4"}'
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    'content-type': "application/json"
    }

response = requests.request("PATCH", url, data=payload, headers=headers)

print(response.text)
curl --request PATCH \
  --url http://localhost:8888/api/2/votes/15/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "value": "4"
}'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/votes/15/",
  "method": "PATCH",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"value": "4"}'
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Sample JSON response:

{
  "id": 10,
  "value": 4,
  "type": "rate",
  "voter_id": null,
  "asset_id": 3,
  "session_id": 1,
  "asset_votes": [
    {
      "total": 1,
      "type": "like"
    },
    {
      "total": 2,
      "type": "rate",
      "avg": 4.5
    }
  ]
}

Update Vote.

HTTP Request

PATCH localhost:8888/api/2/votes/:id/

Optional Parameters

Data format: application/json

Partial update allowed; params not included will leave field values unchanged.

Parameter Format Sample Description/Notes
session_id integer 7
asset_id integer 9
type integer 18 OPTIONS: flag, like, rate, block_asset, block_user
value integer 3 only used with rate currently

DELETE votes/:id/

import requests

url = "http://localhost:8888/api/2/votes/5/"

payload = ""
headers = {
    'authorization': "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
    }

response = requests.request("DELETE", url, data=payload, headers=headers)

print(response.text)
curl --request DELETE \
  --url http://localhost:8888/api/2/votes/5/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/votes/5/",
  "method": "DELETE",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "data": ""
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Returns 204 No Content if successful

Delete Vote.

HTTP Request

DELETE localhost:8888/api/2/votes/:id/

Errors

The Kittn API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
403 Forbidden – The kitten requested is hidden for administrators only
404 Not Found – The specified kitten could not be found
405 Method Not Allowed – You tried to access a kitten with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The kitten requested has been removed from our servers
418 I’m a teapot
429 Too Many Requests – You’re requesting too many kittens! 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.