Roundware API V2

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.

The source for these docs is kept in a public Git repository: roundware-api-docs. Please feel free to issue a PR if you find anything contained herein that is wrong or needs more clarification. Thanks!

Initial testing setup

Run POST api/2/users/ to get token.
Use token for all subsequent api calls.
Run request sequences in Common Scenarios as desired.

API Design Guidelines

In an attempt to be consistent across API calls, here are some guidelines for api/2/ calls. These provide the basis for many design decisions and should help anyone implementing the API. This said, exceptions must be made in some cases, so expect occasional inconsistencies, most of which are likely by design, but some of which may not be(!).

All resources are plural.
Methods
- GET - View the resource
- POST - Create the resource
- PUT - Replace the resource (not currently used)
- PATCH - Update the resource
- DELETE - Delete the resource
For POST and PATCH calls, the object being created should be at the root of the url i.e. POST api/2/sessions/ and any further parameters should be added as POST params, preferably in application/json form, but can be multipart/form-data as needed.
Any ids included in urls should refer to the item immediately preceding them in the url itself. The following returns data about Project with id=2:

GET api/2/projects/2/

Generally speaking, a call that changes or creates an object should represent the entire new object in its response. This will allow for a easy verification of application state for the API consuming client.
all calls should have example calls and example responses showing all possible params (optional and otherwise) to make it easier for those adopting the protocol.

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

You must replace 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4 with your token generated by the users/ endpoint.

Common Scenarios

The following are common sequences of API calls that are useful both for testing as well as for implementation. Most core Roundware functionality requires a series of API calls to accomplish the desired result.

Initialize Client

Roundware clients will need to make a series of requests to the server to initialize and configure the UI.

1. Get token

Making a request to the users/ endpoint with unique device_id returns a token to be used with all subsequent requests.

POST localhost:8888/api/2/users/

2. Establish Session

Each time a Roundware client is instantiated, it needs to create a new Session:

POST localhost:8888/api/2/sessions/

3. Get Project Info

Various config data is stored on the server to maximize flexibility and is used to initialize Roundware client UIs as well as control certain functionality. Currently, clients are all single-project and therefore have their project_id hard-coded, but in the future, clients will be able to choose from available projects and will subsequently send the selected project_id to the server in this request.

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

4. Get Tag Info

Tags are also stored on the server and are retrieved for use in the UI.

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

5. Get UI Info

Tags are grouped and ordered within client UIs based on data stored in UI Groups and UI Items

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

These are the basic initialization steps, though some projects will require variations and/or additions to these.

Request Stream

1. Create Stream

Streams are created on a one-to-one relationship with Sessions. A Stream can be re-created during a Session as needed, but the stream_id will remain the unchanged and the same as session_id.

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

2. Move Listener

Every time the Roundware client senses a new position, it sends a PATCH streams/ request with the updated latitude and longitude values which cause the server to remix the Speaker audio and filter the available Assets in the playlist.

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

3. Modify Stream

Users can filter their Stream by Tags. This is the same PATCH streams/ request as for location changes and can in fact be combined by including tag_ids latitude and longitude params in the same request.

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

Upload Asset

1. Create Envelope

Envelopes are used to bundle Assets together and all Assets, even if not bundled, require an associated Envelope.

POST localhost:8888/api/2/envelopes/

2. Update Envelope With Asset

An Asset is created locally on the client and then uploaded to the server in a PATCH envelopes/ request which includes the binary file as well as all associated metadata.

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

users/

Definition

Roundware uses Django Rest Framework token authorization. Roundware clients generate initial anonymous user accounts in order to retain the ease of use of not requiring an account sign-up process while benefitting from some of the security measures tokened accounts provide.

Users will be able to claim their accounts or register on initial startup in the future.

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);
});

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

This request either creates a new anonymous Roundware User and associated token if the provided device_id does not already exist, or otherwise returns the username and token already associated with the provided device_id.

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);
});

[
  {
    "id": 1,
    "description": "",
    "latitude": 1,
    "longitude": 1,
    "shape": {
        "type": "MultiPolygon",
        "coordinates": [[[[0,0], [0,1], [1,1], [1,0], [0,0]]]]
    },
    "filename": "rw_test_audio1.wav",
    "file": null,
    "volume": 1,
    "submitted": true,
    "created": "2012-07-24T18:06:40",
    "weight": 50,
    "project": 1,
    "language_id": 1,
    "description_loc_ids": [],
    "alt_text_loc_ids": [],
    "media_type": "audio",
    "audio_length_in_seconds": 30,
    "tag_ids": [8,3,5],
    "session_id": 1,
    "envelope_ids": [1]
  },
  {
    "id": 2,
    "description": "",
    "latitude": 1,
    "longitude": 1,
    "shape": null,
    "filename": "20170415-163557-1.wav",
    "file": "/rwmedia/20170415-163557-1.wav",
    "volume": 1,
    "submitted": true,
    "created": "2017-04-15T16:35:57.616822",
    "weight": 50,
    "project": 1,
    "language_id": 1,
    "description_loc_ids": [],
    "alt_text_loc_ids": [],
    "media_type": "audio",
    "audio_length_in_seconds": 24.81,
    "tag_ids": [3,8],
    "session_id": 1,
    "envelope_ids": [2]
  }
]

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_ids	list of integers	can be single id in list
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

Note — Adding GET param admin=1 to this request will provide all localized strings in response, not only English.

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);
});

{
  "id": 1,
  "description": "",
  "latitude": 1,
  "longitude": 1,
  "shape": {
      "type": "MultiPolygon",
      "coordinates": [[[[0,0], [0,1], [1,1], [1,0], [0,0]]]]
  },
  "filename": "rw_test_audio1.wav",
  "file": null,
  "volume": 1,
  "submitted": true,
  "created": "2012-07-24T18:06:40",
  "weight": 50,
  "project": 1,
  "language_id": 1,
  "description_loc_ids": [],
  "alt_text_loc_ids": [],
  "media_type": "audio",
  "audio_length_in_seconds": 30,
  "tag_ids": [8,3,5],
  "session_id": 1,
  "envelope_ids": [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);
});

{
  "id": 1,
  "description": "",
  "latitude": 1,
  "longitude": 1,
  "shape": {
      "type": "MultiPolygon",
      "coordinates": [[[[0,0], [0,1], [1,1], [1,0], [0,0]]]]
  },
  "filename": "rw_test_audio1.wav",
  "file": "/rwmedia/rw_test_audio1.wav",
  "volume": 1,
  "submitted": true,
  "created": "2012-07-24T18:06:40",
  "weight": 50,
  "project": 1,
  "language_id": 1,
  "description_loc_ids": [47,48],
  "alt_text_loc_ids": [49,50],
  "media_type": "audio",
  "audio_length_in_seconds": 30,
  "tag_ids": [8,3,5],
  "session_id": 1,
  "envelope_ids": [1]
}

Create new Asset.

Asset must be added to pre-existing Envelope.

HTTP Request

POST localhost:8888/api/2/assets/

Required Parameters

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

Optional Parameters

Parameter	Format	Sample	Description/Notes
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
tag_ids	comma-separated list	3,4
volume	float	1.234	default = 1.0
weight	integer	34	must be between 0-99; default = 50
description_loc_ids	comma-separated list	6,7	ids of localized strings
alt_text_loc_ids comma-separated list	9,10	ids of localized strings

PATCH assets/

import requests

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

payload = "{"latitude": 2.789,"longitude": 2.1,"tag_ids": [3,4,5],"submitted": false,"description": "","description_loc_ids": [5,7],"alt_text_loc_ids": [7,9],"volume": 0.543,"weight": 89,"language_id": 1,"project_id": 1}"
headers = {
    'authorization': "token aed40ccd8bbc291bf04ccea20627cd8f83eee9ca",
    '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/assets/24/' \
  --header 'authorization: token aed40ccd8bbc291bf04ccea20627cd8f83eee9ca' \
  --header 'content-type: application/json' \
  --data '{
      "latitude": 2.789,
      "longitude": 2.1,
    "tag_ids": [3,4,5],
    "submitted": false,
    "description": "",
    "description_loc_ids": [5,7],
    "alt_text_loc_ids": [7,9],
    "volume": 0.543,
    "weight": 89,
    "language_id": 1,
    "project_id": 1
}'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/assets/24/",
  "method": "PATCH",
  "headers": {
    "authorization": "token aed40ccd8bbc291bf04ccea20627cd8f83eee9ca",
    "content-type": "application/json"
  },
  "processData": false,
  "data": "{"latitude": 2.789,"longitude": 2.1,"tag_ids": [3,4,5],"submitted": false,"description": "","description_loc_ids": [5,7],"alt_text_loc_ids": [7,9],"volume": 0.543,"weight": 89,"language_id": 1,"project_id": 1}"
}

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

{
  "id": 1,
  "description": "",
  "latitude": 2.789,
  "longitude": 2.1,
  "shape": {
      "type": "MultiPolygon",
      "coordinates": [[[[0,0], [0,1], [1,1], [1,0], [0,0]]]]
  },
  "filename": "rw_test_audio1.wav",
  "file": "/rwmedia/rw_test_audio1.wav",
  "volume": 1,
  "submitted": false,
  "created": "2012-07-24T18:06:40",
  "weight": 50,
  "caption_loc_ids": null,
  "project": 1,
  "language_id": 1,
  "description_loc_ids": [5,7],
  "alt_text_loc_ids": [7,9],
  "media_type": "audio",
  "audio_length_in_seconds": 30,
  "tag_ids": [3,4,5],
  "session_id": 1,
  "envelope_ids": [1]
}

Update Asset.

Not all fields are available for update for various reasons.

HTTP Request

PATCH localhost:8888/api/2/assets/

Optional Parameters

Data format: application/json

Parameter	Format	Sample	Description/Notes
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
tag_ids	array of integers	[1,2,3]
volume	float	1.45
weight	integer	80	range: 0-99
language_id	integer	2
project_id	integer	1
description	string	this is a transcript of the audio or other useful info
description_loc_ids	array of integers	[10,21]
alt_text_loc_ids	array of integers	[32,2]

DELETE assets/:id/

import requests

url = "http://localhost:8888/api/2/assets/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/assets/5/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/assets/5/",
  "method": "DELETE",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  },
  "processData": false,
  "data": ""
}

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

Delete Asset

HTTP Request

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

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);
});

[
  {
    "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);
});

{
  "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"
    }
  ]
}

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

GET assets/random/

import requests

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

querystring = {"limit":"2", "project_id":"1", "submitted":"true", "media_type":"audio", "audiolength__lte":"30", "audiolength__gte":"10"}

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/?limit=2&mediatype=audio&submitted=true&project_id=1&audiolength__lte=30&audiolength__gte=15' \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/assets/?limit=2&mediatype=audio&submitted=true&project_id=1&audiolength__lte=30&audiolength__gte=15",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

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

[
    {
        "id": 7786,
        "description": "waldman-66",
        "latitude": 42.3746271119689,
        "longitude": -71.1146264076236,
        "shape": null,
        "filename": "20150502-163007.wav",
        "file": "/rwmedia/20150502-163007.wav",
        "volume": 1,
        "submitted": true,
        "created": "2015-05-02T16:30:08",
        "weight": 50,
        "caption_loc_ids": null,
        "project": 19,
        "language_id": 1,
        "description_loc_ids": [],
        "alt_text_loc_ids": [],
        "media_type": "audio",
        "audio_length_in_seconds": 15.16,
        "tag_ids": [
            222,
            226
        ],
        "session_id": -10,
        "envelope_ids": [1]
    },
    {
        "id": 8107,
        "description": "",
        "latitude": 42.37447,
        "longitude": -71.116654,
        "shape": null,
        "filename": "20151026-225822.wav",
        "file": "/rwmedia/20151026-225822.m4a",
        "volume": 1,
        "submitted": true,
        "created": "2015-10-26T22:58:22",
        "weight": 50,
        "caption_loc_ids": null,
        "project": 19,
        "language_id": 1,
        "description_loc_ids": [],
        "alt_text_loc_ids": [],
        "media_type": "audio",
        "audio_length_in_seconds": 19.48,
        "tag_ids": [
            219
        ],
        "session_id": 23111,
        "envelope_ids": [2]
    }
]

Get random list of Assets.

HTTP Request

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

Optional Filters

Parameter	Format	Description/Notes
limit	integer	how many Assets included in response?
project_id	integer
media_type	string	audio, photo, text, video
submitted	boolean
audiolength__lte	double	in seconds
audiolength__gte	double	in seconds

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);
});

[
  {
    "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);
});

{
  "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);
});

{
  "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);
});

{
  "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);
});

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.

GET envelopes/

import requests

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

querystring = {"project_id":"1"}

headers = {'authorization': 'token aed40ccd8bbc291bf04ccea20627cd8f83eee9ca'}

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

print(response.text)

curl --request GET \
  --url 'http://localhost:8888/api/2/envelopes/?project_id=1' \
  --header 'authorization: token aed40ccd8bbc291bf04ccea20627cd8f83eee9ca'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/envelopes/?project_id=1",
  "method": "GET",
  "headers": {
    "authorization": "token aed40ccd8bbc291bf04ccea20627cd8f83eee9ca"
  }
}

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

[
    {
        "id": 2,
        "session_id": 3,
        "created": "2017-09-30T22:57:09.446813",
        "asset_ids": [1]
    },
    {
        "id": 1,
        "session_id": 1,
        "created": "2013-01-21T10:36:44",
        "asset_ids": [2, 3, 4, 5]
    }
]

Get list of Envelopes.

HTTP Request

GET localhost:8888/api/2/envelopes/

Optional Filters

Parameter	Format	Description/Notes
project_id	integer
session_id	integer
asset_id	integer

GET envelopes/:id/

import requests

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

headers = {'authorization': 'token aed40ccd8bbc291bf04ccea20627cd8f83eee9ca'}

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

print(response.text)

curl --request GET \
  --url 'http://localhost:8888/api/2/envelopes/1/' \
  --header 'authorization: token aed40ccd8bbc291bf04ccea20627cd8f83eee9ca'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/envelopes/1/",
  "method": "GET",
  "headers": {
    "authorization": "token aed40ccd8bbc291bf04ccea20627cd8f83eee9ca"
  }
}

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

{
    "id": 1,
    "session_id": 1,
    "created": "2013-01-21T10:36:44",
    "asset_ids": [2, 3, 4, 5]
}

Get specific Envelope.

HTTP Request

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

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);
});

{
  "session_id": 3,
  "created": "2017-06-07T13:07:58.247988",
  "asset_ids": [],
  "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);
});

{
  "description": "",
  "latitude": 1,
  "longitude": 1,
  "shape": null,
  "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,
  "envelope_ids": [1]
}

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.

asset.submitted is set automatically according to the following cascading set of checks:

is submitted parameter passed in request?
- if YES, asset.submitted set to this value
- if NO, then check if latitude and longitude parameters are both passed
  - if NO, asset.submitted False and latitude = project.latitude and longitude = project.longitude
  - if YES, then check if location in range of Project
    - if NO, asset.submitted = False
    - if YES, asset.submitted = project.auto_submit

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
media_type	enum	audio,photo,text,video	default is audio

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);
});

[
  {
    "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);
});

{
  "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);
});

{
  "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);
});

[
  {
    "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);
});

{
  "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);
});

{
  "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);
});

{
  "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);
});

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);
});

[
  {
    "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);
});

{
  "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_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/localizedstrings/?localized_string=roundware&language_id=1' \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/localizedstrings/?localized_string=roundware&language_id=1",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

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

[
  {
    "id": 2,
    "language": "en",
    "language_id": 1,
    "text": "Why are you using Roundware?"
  },
  {
    "id": 47,
    "language": "en",
    "language_id": 1,
    "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
language_id	integer
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);
});

{
  "id": 2,
  "language": "en",
  "language_id": 1,
  "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 = '{"text":"This is a new localized string.", "language_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/localizedstrings/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "text": "This is a new localized string.",
  "language_id": 1,
}'

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": '{"text":"This is a new localized string.", "language_id":1}'
}

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

{
  "id": 3,
  "language": "en",
  "language_id": 1,
  "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
text	string	Hello
language_id	integer	1	Validates to existing

PATCH languages/:id/

import requests

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

payload = '{"text":"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 '{"text":"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": '{"text":"This is an updated localized string."}'
}

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

{
  "id": 3,
  "language": "en",
  "language_id": 1,
  "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);
});

Delete Localized String

HTTP Request

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

Definition

In addition to the built-in Django Admin, Roundware uses an Angular-based web admin system that is designed to provide a more user-friendly interface to the higher-level Roundware features. Web Admin users can do all the basic setup and content management required to initiate and maintain a Roundware installation, but may still need the Django admin for certain lower-level tasks.

The RW Web Admin uses the standard Django Authorization system, so the login/ endpoint was created to authorize users by taking username and password and returning the associated token which is used for future api requests. Users must be designated as Staff in the auth system in order to login into the Web Admin. Code for the Web Admin is in a separate repository and can be found here: GitHub - Roundware Admin

import requests

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

payload = '{"username": "round","password": "round"}'
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/login/ \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4' \
  --header 'content-type: application/json' \
  --data '{
  "username": "round",
  "password": "round"
}'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/login/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": '{"username": "round","password": "round"}'
}

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

{
  "token": "4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
}

HTTP Request

POST localhost:8888/api/2/login/

Required Parameters

Data format: application/json

Parameter	Sample Data	Default	Description/Notes
username	round	string	as found in Django auth
password	round	string	as found in Django auth

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);
});

[
  {
    "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);
});

{
  "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

Note — Adding GET param admin=1 to this request will provide all localized strings in response, not only English.

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);
});

[
  {
    "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

Note — Adding GET param admin=1 to this request will provide all localized strings in response, not only English.

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);
});

{
  "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

Note — Adding GET param admin=1 to this request will provide all localized strings in response, not only English.

GET projects/:id/uiconfig/

import requests

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

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/projects/1/uiconfig/?session_id=1 \
  --header 'authorization: token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/projects/1/uiconfig/?session_id=1",
  "method": "GET",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

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

{
    "speak": [
        {
            "select": "single",
            "group_short_name": "Gender",
            "header_display_text": "What gender are you?",
            "display_items": [
                {
                    "id": 8,
                    "tag_id": 3,
                    "parent_id": null,
                    "default_state": false,
                    "tag_display_text": "male"
                },
                {
                    "id": 171,
                    "tag_id": 4,
                    "parent_id": null,
                    "default_state": false,
                    "tag_display_text": "female"
                }
            ]
        },
        {
            "select": "single",
            "group_short_name": "Usertype",
            "header_display_text": "Who are you?",
            "display_items": [
                {
                    "id": 173,
                    "tag_id": 23,
                    "parent_id": 171,
                    "default_state": false,
                    "tag_display_text": "Curator"
                },
                {
                    "id": 143,
                    "tag_id": 9,
                    "parent_id": 8,
                    "default_state": false,
                    "tag_display_text": "Visitor"
                },
                {
                    "id": 172,
                    "tag_id": 9,
                    "parent_id": 171,
                    "default_state": false,
                    "tag_display_text": "Visitor"
                },
                {
                    "id": 142,
                    "tag_id": 8,
                    "parent_id": 8,
                    "default_state": false,
                    "tag_display_text": "Artist"
                },
                {
                    "id": 180,
                    "tag_id": 8,
                    "parent_id": 171,
                    "default_state": false,
                    "tag_display_text": "Artist"
                }
            ]
        },
        {
            "select": "single",
            "group_short_name": "Question",
            "header_display_text": "What do you want to talk about?",
            "display_items": [
                {
                    "id": 178,
                    "tag_id": 26,
                    "parent_id": 172,
                    "default_state": false,
                    "tag_display_text": "Who are you?"
                },
                {
                    "id": 174,
                    "tag_id": 26,
                    "parent_id": 173,
                    "default_state": false,
                    "tag_display_text": "Who are you?"
                },
                {
                    "id": 148,
                    "tag_id": 5,
                    "parent_id": 143,
                    "default_state": false,
                    "tag_display_text": "Why are you using Roundware?"
                },
                {
                    "id": 175,
                    "tag_id": 22,
                    "parent_id": 173,
                    "default_state": false,
                    "tag_display_text": "Respond to something you've heard."
                },
                {
                    "id": 177,
                    "tag_id": 22,
                    "parent_id": 172,
                    "default_state": false,
                    "tag_display_text": "Respond to something you've heard."
                },
                {
                    "id": 152,
                    "tag_id": 22,
                    "parent_id": 142,
                    "default_state": false,
                    "tag_display_text": "Respond to something you've heard."
                },
                {
                    "id": 149,
                    "tag_id": 22,
                    "parent_id": 143,
                    "default_state": false,
                    "tag_display_text": "Respond to something you've heard."
                },
                {
                    "id": 155,
                    "tag_id": 26,
                    "parent_id": 142,
                    "default_state": false,
                    "tag_display_text": "Who are you?"
                },
                {
                    "id": 176,
                    "tag_id": 5,
                    "parent_id": 173,
                    "default_state": false,
                    "tag_display_text": "Why are you using Roundware?"
                },
                {
                    "id": 179,
                    "tag_id": 5,
                    "parent_id": 172,
                    "default_state": false,
                    "tag_display_text": "Why are you using Roundware?"
                }
            ]
        }
    ],
    "listen": [
        {
            "select": "min_one",
            "group_short_name": "Gender",
            "header_display_text": "What genders do you want to listen to?",
            "display_items": [
                {
                    "id": 79,
                    "tag_id": 3,
                    "parent_id": null,
                    "default_state": true,
                    "tag_display_text": "male"
                },
                {
                    "id": 164,
                    "tag_id": 4,
                    "parent_id": null,
                    "default_state": false,
                    "tag_display_text": "female"
                }
            ]
        },
        {
            "select": "min_one",
            "group_short_name": "Usertype",
            "header_display_text": "Who do you want to hear?",
            "display_items": [
                {
                    "id": 165,
                    "tag_id": 23,
                    "parent_id": null,
                    "default_state": false,
                    "tag_display_text": "Curator"
                },
                {
                    "id": 166,
                    "tag_id": 9,
                    "parent_id": null,
                    "default_state": false,
                    "tag_display_text": "Visitor"
                },
                {
                    "id": 167,
                    "tag_id": 8,
                    "parent_id": null,
                    "default_state": false,
                    "tag_display_text": "Artist"
                }
            ]
        },
        {
            "select": "min_one",
            "group_short_name": "Question",
            "header_display_text": "What do you want to listen to?",
            "display_items": [
                {
                    "id": 168,
                    "tag_id": 26,
                    "parent_id": null,
                    "default_state": false,
                    "tag_display_text": "Who are you?"
                },
                {
                    "id": 169,
                    "tag_id": 5,
                    "parent_id": null,
                    "default_state": false,
                    "tag_display_text": "Why are you using Roundware?"
                },
                {
                    "id": 170,
                    "tag_id": 22,
                    "parent_id": null,
                    "default_state": false,
                    "tag_display_text": "Respond to something you've heard."
                }
            ]
        }
    ]
}

This is a convenience request to facilitate client UI construction. Rather than having to make projects/:id/uiconfig/, projects/:id/tags/ and projects/:id/tagcategories/ requests and then weaving them together, this request returns all and the only data a client needs to setup both listen and speak tag filtering screens. Ordering is enforced in response.

Default behavior is for Listen display_items to show one per tag_id since default Listen tag filtering will not filter display_items by user selections since there is no imposed order of user interaction as in Speak. For Speak, multiple display_items with the same tag_id can be included as they will have different parent_ids, allowing the client to filter the available display_items in each group based on previous user selections. For more complicated or non-standard client implementations, the lower level model api request can be used.

HTTP Request

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

Parameters

Parameter	Format	Description/Notes
session_id	integer	used to localize response strings

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);
});

{
  "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

Note — Adding GET param admin=1 to this request will provide all localized strings in response, not only English.

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);
});

{
  "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);
});

{
  "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);
});

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.

GET sessions/

import requests

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

querystring = {"project_id":"1","language_id":"2","language":"en","geo_listen_enabled":"false","demo_stream_enabled":"true"}

headers = {'authorization': 'token aed40ccd8bbc291bf04ccea20627cd8f83eee9ca'}

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

print(response.text)

curl --request GET \
  --url 'http://localhost:8888/api/2/sessions/?project_id=1&language_id=2&language=en&geo_listen_enabled=false&demo_stream_enabled=true' \
  --header 'authorization: token aed40ccd8bbc291bf04ccea20627cd8f83eee9ca'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/sessions/?project_id=1&language_id=2&language=en&geo_listen_enabled=false&demo_stream_enabled=true",
  "method": "GET",
  "headers": {
    "authorization": "token aed40ccd8bbc291bf04ccea20627cd8f83eee9ca"
  }
}

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

[
    {
        "id": 109,
        "device_id": null,
        "starttime": "2017-09-06T15:43:35.947761",
        "stoptime": null,
        "client_type": null,
        "client_system": "iOS 8.1",
        "demo_stream_enabled": true,
        "geo_listen_enabled": false,
        "timezone": "-8000",
        "project_id": 1,
        "language_id": 2
    },
    {
        "id": 111,
        "device_id": null,
        "starttime": "2017-09-06T16:24:32.647751",
        "stoptime": null,
        "client_type": null,
        "client_system": "iOS 8.1",
        "demo_stream_enabled": true,
        "geo_listen_enabled": false,
        "timezone": "-8000",
        "project_id": 1,
        "language_id": 2
    }
]

Get list of Sessions.

HTTP Request

GET localhost:8888/api/2/sessions/

Optional Filters

Parameter	Format	Description/Notes
project_id	integer
language_id	integer
language	string	2-char ISO shortcode
geo_listen_enabled	boolean
demo_stream_enabled	boolean

GET sessions/:id/

import requests

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

headers = {'authorization': 'token aed40ccd8bbc291bf04ccea20627cd8f83eee9ca'}

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

print(response.text)

curl --request GET \
  --url 'http://localhost:8888/api/2/sessions/1/' \
  --header 'authorization: token aed40ccd8bbc291bf04ccea20627cd8f83eee9ca'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8888/api/2/sessions/1/",
  "method": "GET",
  "headers": {
    "authorization": "token aed40ccd8bbc291bf04ccea20627cd8f83eee9ca"
  }
}

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

{
    "id": 1,
    "device_id": null,
    "starttime": "2017-09-06T16:24:32.647751",
    "stoptime": null,
    "client_type": null,
    "client_system": "iOS 8.1",
    "demo_stream_enabled": true,
    "geo_listen_enabled": false,
    "timezone": "-8000",
    "project_id": 1,
    "language_id": 2
}

Get specific Session.

HTTP Request

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

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);
});

{
  "client_system": "iOS 8.1",
  "client_type": "iPhone",
  "demo_stream_enabled": false,
  "device_id": "12891038109281",
  "geo_listen_enabled": true,
  "language_id": 1,
  "project_id": 1,
  "starttime": "2017-06-09T02:42:03.939255",
  "stoptime": null,
  "timezone": "0000",
  "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
client_type	string		defaults to value in related session if not passed
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
language_id	integer	1	if both language and language_id are passed, language takes precedence
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);
});

[
  {
    "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);
});

{
  "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);
});

{
  "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);
});

{
  "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);
});

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).

Note — streams/ is the only endpoint that does not correspond to a model. Streams are created and manipulated in real-time on a session-by-session basis and only exist while a session is active.

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);
});

{
  "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);
});

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

Optional Parameters

Data format: multipart/form-data

Parameter	Format	Sample	Description/Notes
listener_range_max	integer	10000	maximum distance threshold in meters
listener_range_min	integer	1000	minimum distance threshold in meters, default = 0
listen_heading	float	55.0	compass heading of directional listening (degrees)
listen_width	float	10.0	width of listening “beam” (degrees), default=10

Range Listening Mode

If the listener_range_max parameter is included in request, the stream switches to “range listening” mode in which assets are added to the playlist based on being located within a distance threshold determined by the user. This allows users to choose to listen to content that is much further from them physically than would normally be accessible in geo_listen_enabled mode. The listener_range_max parameter must be included in every request for which client wishes to remain in range listening mode; if not included, stream will default back to standard listening mode for the project (geo or global listening).

By default, listener_range_min is set to 0. If client includes listener_range_min in request in addition to listener_range_max, the playlist will be filtered for assets that are more than listener_range_min and less than listener_range_max from the listener.

Directional Listening Mode

If listen_heading is included in a request with a valid value, the stream switches to “directional listening” mode in which assets are added to the playlist based on being located in the specified direction (compass heading) from the listener. listen_width specifies how many degrees (centered around listen_heading) the “listening beam” should extend. The lower the value, the thinner and more focussed the beam becomes.

listener_range_min/max parameters can be used in combination with directional listening to provide a direction as well as a distance range to filter for available assets. With no range parameters included in request, all assets from the listener’s location to the antipodal location on the other side of the earth will be heard. The listener_range_max parameter must be included in every request for which client wishes to remain in range listening mode; if not included, stream will default back to standard listening mode for the project (geo or global listening).

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);
});

Update Stream with new tag filters.

This request filters the playlist of Assets, but for geo_listen_enabled Sessions, only updates the in-range Assets if latitude and longitude are also included in the PATCH data. Therefore, it is best practice to include latitude and longitude in these requests for geo_listen_enabled projects.

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);
});

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);
});

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);
});

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/skipasset/

import requests

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

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/skipasset/ \
  --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/skipasset/",
  "method": "POST",
  "headers": {
    "authorization": "token 4ee0fc210823c2c2f72f06e3fe862c0f6740d3b4"
  }
}

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

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

HTTP Request

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

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);
});

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);
});

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);
});

{
  "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);
});

[
  {
    "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);
});

{
  "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);
});

{
  "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);
});

{
  "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);
});

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);
});

[
  {
    "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);
});

{
  "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);
});

{
  "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);
});

{
  "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);
});

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);
});

{
  "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

Note — Adding GET param admin=1 to this request will provide all localized strings in response, not only English.

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);
});

{
  "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);
});

{
  "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
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);
});

{
  "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);
});

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);
});

[
  {
    "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
asset_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);
});

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

Get specific Timed Asset.

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);
});

{
  "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);
});

{
  "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);
});

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);
});

{
  "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

Note — Adding GET param admin=1 to this request will provide all localized strings in response, not only English.

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);
});

{
  "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);
});

{
  "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);
});

{
  "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);
});

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);
});

[
  {
    "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);
});

{
  "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);
});

{
  "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);
});

{
  "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);
});

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);
});

[
  {
    "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);
});

{
  "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);
});

{
  "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);
});

{
  "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);
});

Delete Vote.

HTTP Request

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

Testing

We love tests, but need more, so feel free to contribute(!).

Unit tests

We have unit tests, but no where near full coverage at this point, so we need to do additional testing.

To run unit tests:

./scripts/tests.sh

To run individual unit test (for example):

./tests.sh tests.roundwared.test_recording_collection.TestRecordingCollection

Stream testing script

We have a script that starts up a stream and then moves the listener in and out of range of the default asset at lat/lon 1/1. To run this test:

./scripts/stream-test.sh

You can add additional ambient test assets to project #1 using this script:

./scripts/add-test-audio.py

Errors

Django REST Framework has a standard way of returning error conditions in which the HTTP status code is the measure of success, and the JSON response body includes a single "detail" field with the cause of error. In the interest of not fighting the framework, most Roundware endpoints operate in the same manner. Errors will present a HTTP 400 BAD REQUEST, along with a detail field for explanation in most cases. Success will be in the form of a HTTP 200, along with a response body filled with relevant resulting data if any exists.