HTTP reference¶

This API was primarily designed for and is consumed by our own GM interface. It likely returns much more data than you will want, and there are opportunities for usage patterns that differ from ours to generate a significant load on our servers.

Take a look at the requests our GM interface makes (via dev tools network tab), and try not to deviate too heavily. Contact us if you need a more efficient way to fetch bulk data, or need more/less data generally.

Get started¶

Authentication¶

Authenticate requests with an authorization: token {TOKEN} header or ?auth_token={TOKEN} query param.

Users who have a Syrinscape account can get their auth token at https://syrinscape.com/account/auth-token/.

Formats¶

Some endpoints return HTML or JSON. For those endpoints, force a JSON response with an accept: application/json header or ?format=json query param.

Get config¶

Get the current session_id and device_name for an authenticated user.

HTTP

GET https://app.syrinscape.com/config/ HTTP/1.1
accept: application/json
authorization: token {TOKEN}

A new token will be created for an anonymous user.

HTTP

GET https://app.syrinscape.com/config/ HTTP/1.1
accept: application/json

Important

You should persist the returned token and use it to authenticate all subsequent requests for the user.

New session¶

Create a new session_id and make it current for the authenticated user.

HTTP

GET https://app.syrinscape.com/new/ HTTP/1.1
accept: application/json
authorization: token {TOKEN}

Content¶

List soundsets¶

HTTP

GET https://syrinscape.com/online/frontend-api/soundsets/ HTTP/1.1
accept: application/json
authorization: token {TOKEN}

List moods for a soundset¶

HTTP

GET https://syrinscape.com/online/frontend-api/moods/?soundset__uuid=30e64e78-a7e1-11e2-ab8f-68a86d087c62 HTTP/1.1
accept: application/json
authorization: token {TOKEN}

List elements for a soundset¶

HTTP

GET https://syrinscape.com/online/frontend-api/elements/?soundset__uuid=30e64e78-a7e1-11e2-ab8f-68a86d087c62 HTTP/1.1
accept: application/json
authorization: token {TOKEN}

Warning

Only request moods and elements for individual soundsets as you need them. Do not iterate soundsets and request mood and element data in bulk.

Control a session¶

Start a mood¶

HTTP

POST https://syrinscape.com/online/frontend-api/moods/{MOOD_ID}/play/ HTTP/1.1
accept: application/json
authorization: token {TOKEN}

Start an element¶

HTTP

POST https://syrinscape.com/online/frontend-api/elements/{ELEMENT_ID}/play/ HTTP/1.1
accept: application/json
authorization: token {TOKEN}

Stop a mood¶

HTTP

POST https://syrinscape.com/online/frontend-api/moods/{MOOD_ID}/stop/ HTTP/1.1
accept: application/json
authorization: token {TOKEN}

Stop an element¶

HTTP

POST https://syrinscape.com/online/frontend-api/elements/{ELEMENT_ID}/stop/ HTTP/1.1
accept: application/json
authorization: token {TOKEN}

Stop all¶

HTTP

POST https://syrinscape.com/online/frontend-api/stop-all/ HTTP/1.1
accept: application/json
authorization: token {TOKEN}

Get global and oneshot volume¶

HTTP

GET https://syrinscape.com/online/frontend-api/state/ HTTP/1.1
accept: application/json
authorization: token {TOKEN}

Set global volume¶

HTTP

POST https://syrinscape.com/online/frontend-api/global-volume/{VOLUME}/ HTTP/1.1
accept: application/json
authorization: token {TOKEN}

Volume can be given as an absolute value between 0.0 and 1.5 (150%), or an incremental change with a + or - prefix (e.g. +0.05).

Set oneshot volume¶

HTTP

POST https://syrinscape.com/online/frontend-api/global-oneshot-volume/{VOLUME}/ HTTP/1.1
accept: application/json
authorization: token {TOKEN}

Volume can be given as an absolute value between 0.0 and 1.5 (150%), or an incremental change with a + or - prefix (e.g. +0.05).

Set current element volume¶

HTTP

POST https://syrinscape.com/online/frontend-api/elements/{ELEMENT_ID}/set-current-volume/{VOLUME}/ HTTP/1.1
accept: application/json
authorization: token {TOKEN}

Volume can be given as an absolute value between 0.0 and 1.0 (100%), or an incremental change with a + or - prefix (e.g. +0.05).

Search¶

You can perform a real-time search for relevant content as you need it.

HTTP

GET https://syrinscape.com/search/?q=bugbear HTTP/1.1
accept: application/json
authorization: token {TOKEN}

Query¶

q

"Query".

exactly match single-word "terms" and "multi-word phrases"
exclude -terms and -"exact matches"
wildc* (wildcard) terms
boost terms^5 and "exact matches"^10
() precedence
+ AND
| OR

Filters¶

Specify a filter multiple times if you want to return results matching multiple values (OR).

HTTP

GET https://syrinscape.com/search/?kind=SFX&kind=Oneshots HTTP/1.1
accept: application/json
authorization: token {TOKEN}

genre: General Fantasy, Dungeons & Dragons, Pathfinder, Sci-Fi, Board Game.
kind: Adventures, Soundsets, Moods, Music, Loops, SFX, Oneshots, Samples.
status: Official Content, Community Content, My Content, Pending Review.
library: Available to Play, Available to Buy.
playing: Playing Now.

Pagination¶

p

"Page". Default 1.

pp

Results "Per Page". Default 100.

pqh

"Prior Query Hash".

Provide the value of query_hash (see results, below) as pqh when paging through results. If the value changes, e.g. because filters have changed, we will go back to page 1.

Results¶

count: Approximate number of results.
filters: [filter_value, filter_type, css_class] for each available filter (see above). Use this to dynamically build a filter interface.
more_pages: Are there more pages of results?
page: Current page.
query: Current query.
query_hash: Hash of query and filters. Provide this as pqh ("prior query hash", see above) when paging through results. If the value changes, we will go back to page 1.
results: [{status: "OFFICIAL", playing_now: false, ...}, ...]

Bulk data export¶

If you want to build up a local database of all available moods and elements for a user, download the remote control links file.

HTTP

GET https://syrinscape.com/account/remote-control-links/ HTTP/1.1
authorization: token {TOKEN}

This returns data for every mood and element available to the user:

Status (official, community, private)
Category (General Fantasy, Dungeons and Dragons, Pathfinder, Sci-Fi, Board Game, etc.)
Store name
Soundset name
Mood or element name
Start/stop URLs for the Fantasy, Sci-Fi and Board Game players
Start/stop URLs for the online player

You will need to add the user's auth token to online player start/stop URLs, or have the relevant Fantasy, Sci-Fi or Board Game player installed.

Warning

Only download this file periodically per user (e.g. once per week, inline with our release schedule) or on demand (e.g. after a user has modified a private soundset).

Info

This data does not currently include the soundset UUID required to list moods and elements for a soundset (see above). We intend to create a new endpoint that returns key data in JSON format.