StreamJar API

Developers can use our API to create their own applications. Information about each endpoint has been included below. We also utilise socket.io, which applications can use for instant tip polling.

This API is in its early stages and is subject to major changes.

Accounts

POST
/account/login

Creates a new session in the context of a user, authenticated with their existing credentials.

Parameters

username

The account's username.

String (required)

password

The account's password.

String (required)

Responses

200
{
  "username": "user",
  "email": "[email protected]"
}
401
{
  "error": "Invalid username or password."
}
POST
/account/login/key

Create a new session in the context of a user, authenticated using the account's personal API key. The user can acquire their unique API key from their Settings page. Users can refresh their key at any time. Authentication attempts with an expired key will fail.

Parameters

key

The account's unique key.

String (required)

Responses

200
{
  "username": "user",
  "email": "[email protected]"
}
401
{
  "error": "Invalid key."
}
GET
/account/logout

Destroy the user's current session.

Responses

200
{
  "status": true
}
POST
/account/signup

Create a new account.

Parameters

username

The account's username. This may only contain letters, numbers, dashes and underscores.

String (required)
Size: 3..16

email

The account's email.

String (required)

password

The account's password.

String (required)

Responses

200
{
  "status": true
}
400
{
  "error": "The credentials you entered are already in use."
}
GET
/account/key

Retrieve the current user's unique key. This key should only be shared with trusted applications. Applications should use the key as a form of authentication, rather than storing the user's credentials. The key can be changed by the user.

Responses

200
{
  "key": "s9l49D14h916ZWl7d00ix57g3Y91RP5q"
}
POST
/account/key

Regenerate the current user's unique key. A random key will be generated, and it will permanently replace the user's API key. Previous versions of the key will not work when authenticating.

Responses

200
{
  "key": "s9l49D14h916ZWl7d00ix57g3Y91RP5q"
}
GET
/account/reset/:username/:token

Check whether a reset request is valid

Parameters

username

The username of the user you wish to reset

String (required)

token

The token of the reset request.

String (required)

Responses

200
{
  "status": true
}
404
{
   "error": "User not found."
}
400
{
   "error": "Incorrect Token"
}
400
{
   "error": "No Reset Request"
}
GET
/account/verify/:username/:token

Verify the user, using the username and token that was emailed to them.

Parameters

username

The username of the user you wish to verify

String (optional)

token

The token of the user you wish to verify.

String (optional)

Responses

200
{
  "status": true
}
404
{
   "error": "User not found."
}
400
{
   "error": "Invalid token."
}
400
{
   "error": "User already verified."
}
POST
/account/forgot

Verify the user, using the username and token that was emailed to them.

Parameters

username

The username of the user you wish to verify

String (required)

Responses

200
{
  "status": true
}
404
{
   "error": "User not found."
}
400
{
   "error": "Invalid Username."
}
400
{
   "error": "User already has pending request."
}
POST
/account/reset/:username/:token

Reset a user's password.

Parameters

username

The username of the user you wish to reset.

String (required)

token

The token of the reset request.

String (required)

password

The user's new password.

String (required)

repeatpassword

The user's new password repeated.

String (required)

Responses

200
{
  "status": true
}
404
{
   "error": "User not found."
}
400
{
   "error": "Passwords don't match"
}
400
{
   "error": "Invalid Request"
}

Account_Preferences

POST
/account/social

Change the current user's handle for one or more social networks. Social networks are shown on the user's donation page.

You may pass each social network as a separate parameter. For example, passing twitter=StreamJar would change the Twitter handle to StreamJar.

Acceptable parameters: twitter, facebook, googleplus, steam, reddit, patreon, playerme, web

All parameters are optional. This means any handles for social networks that are not passed in this request will remain unchanged.

Responses

200
{
  "status": true
}
PATCH
/account/social

Change the current user's handle for a single, specific social network. This will be shown on the user's donation page.

Parameters

network

The name of the social network to set.

String (required)
Allowed values: "twitter", "facebook", "google", "steam", "reddit", "patreon", "playerme", "web"

value

The handle/username of the social media account.

String (required)

Responses

200
{
  "status": true
}
POST
/account/paypal

Change the user's PayPal email address. Any donations will be sent to this PayPal email.

Parameters

email

PayPal email address.

String (required)

Responses

200
{
  "status": true
}
400
{
  "error": "Please specify a valid email address."
}
DELETE
/account/email

Cancel an email change request

Responses

200
{
  "status": true
}
POST
/account/email

Change the authenticated users email address.

Parameters

token

The email change request token (found in an email)

String (optional)

Responses

200
{
  "status": true
}
400
{
   "error": "Invalid token."
}
POST
/account/password

Change the authenticated users password.

Parameters

oldPassword

The accounts old password

String (optional)

newPassword

The accounts new password.

String (optional)

newPasswordAgain

The accounts new password repeated.

String (optional)

Responses

200
{
  "status": true
}
400
{
   "error": "Please ensure that both passwords match"
}
400
{
   "error": "Invalid Password."
}
POST
/account/settings

This is a generic API endpoint used for changing account settings. The type refers to the group of settings to modify. You may then pass the options associated with that group, as separate parameters. You must pass all the possible options for that group.

Type Options
chat donationformat, followerformat, subformat

Parameters

type

The group of settings to modify

String (required)
Allowed values: "chat"

Responses

200
{
  "status": true
}
400
{
  "error": "Invalid settings type."
}
400
{
  "error": "Missing parameter."
}

Donations

GET
/donations

Retrieve the current user's latest donations. The donations will be sorted in descending order.

If you are using key-based authentication, the donator's email address will be excluded.

Parameters

query

The search term. Both the donation's name and email will be searched. If this field is omitted, no search will take place.

String (optional)

date

The oldest possible record to retrieve. You may use textual dates, such as year, month, week, day, or you may specify a Unix time.

Mixed (optional)

order

The field that the donations will be sorted with. The donations will be sorted in descending order by default, but this can be changed by appending the direction to the end of the order. For example, amount:asc. This option is ignored if a query is specified, and the results will be sorted by relevance instead.

String (optional)
Default: created_at
Allowed values: "amount", "created_at"

limit

The maximum number of records to retrieve.

Number (optional)
Default: 20
Size: 1-100

page

The page of donations to retrieve, starting from 0.

Number (optional)
Default: 0

test

Whether test donations created from the control panel should be included in the result.

Boolean (optional)
Default: false

Responses

200
[
  {
    "id": "defedfa1-59f2-44c5-9760-9485ff6caf8a",
    "name": "Donator 1",
    "email": "[email protected]",
    "amount": 8,
    "currency": "USD",
    "message": "Test",
    "fields": {
      "Message": "Test"
    },
    "created_at": "2015-09-04T21:43:23.432Z",
    "test_donation": false
  },
  {
    "id": "f6a2fa8c-30de-4886-979e-c00f94ad30d4",
    "name": "Donator 2",
    "email": "[email protected]",
    "amount": 10.64,
    "currency": "USD",
    "message": "",
    "fields": {},
    "created_at": "2015-09-04T20:04:48.912Z",
    "test_donation": true
  }
]
POST
/donations

Creates a new donation request, which will charge the end user.

Responses

GET
/donators

Retrieve general information on each individual that has donated. This works by grouping all donations based on their email address. All of the donator's previous donations are then summarised.

If multiple people share a single PayPal account and donate, all their donations will be grouped under one donator.

The name, date and currency is based on the most recent donation. The amount is the total amount of money donated across all previous donations, and the count is the number of times the individual has donated.

If you are using key-based authentication, the donator's email address will be excluded.

Parameters

date

The oldest possible record to retrieve. You may use textual dates, such as year, month, week, day, or you may specify a Unix time.

Mixed (optional)

order

The order that donators are received in. The donators will be sorted in descending order.

String (optional)
Default: date
Allowed values: "amount", "date"

limit

The maximum number of records to retrieve.

Number (optional)
Default: 20
Size: 1-100

Responses

200
[
  {
    "name": "Donator 1",
    "email": "[email protected]",
    "avatar": "https://www.gravatar.com/avatar/ce578970da062ce0441d0f68c73b3cc9?s=128&d=identicon&r=PG",
    "currency": "USD",
    "amount": 38.5,
    "count": 2,
    "created_at": "2015-08-23T13:08:32.603Z"
  },
  {
    "name": "Donator 2",
    "email": "[email protected]",
    "avatar": "https://www.gravatar.com/avatar/904b00488ff3975a379f9a79f96bdf9b?s=128&d=identicon&r=PG",
    "currency": "USD",
    "amount": 57,
    "count": 3,
    "created_at": "2015-08-23T13:07:37.341Z"
  }
]
GET
/donators/:email

Retrieve information and statistics for one individual that has previously donated. The donator's PayPal email address is used, since this is the best way of determining whether multiple donations belong to the same person.

The response contains all the donations received under this email address (donations), and the highest donation received (highest). The average and sum statistics are in USD.

The rank is the position number the donator would be in if every donator (grouped by PayPal email address) was ordered by the total amount they have donated. For example, rank 1 would mean this PayPal email address has donated the most money.

Parameters

email

The donator's PayPal email address.

String (required)

Responses

200
{
  "donations": [
     {
       "name": "Name 1",
       "email": "[email protected]",
       "avatar": "https://www.gravatar.com/avatar/01febe7c3748b477afc97606ba7a134d?s=128&d=identicon&r=PG",
       "amount": 10.5,
       "currency": "USD",
       "message": "Message",
       "fields": {
         "music": "spotify:73uc55BT8QAGhAi7leaYqJ"
       },
       "created_at": "2015-08-23T13:08:32.603Z"
     },
     {
       "name": "Name 2",
       "email": "[email protected]",
       "avatar": "https://www.gravatar.com/avatar/01febe7c3748b477afc97606ba7a134d?s=128&d=identicon&r=PG",
       "amount": 18.25,
       "currency": "USD",
       "message": "Message",
       "fields": {},
       "created_at": "2015-08-23T08:50:58.877Z"
     }
  ],
  "highest": {
    "name": "Name 2",
    "email": "[email protected]",
    "avatar": "https://www.gravatar.com/avatar/01febe7c3748b477afc97606ba7a134d?s=128&d=identicon&r=PG",
    "amount": 18.25,
    "currency": "USD",
    "message": "Message",
    "fields": {},
    "created_at": "2015-08-23T08:50:58.877Z"
  },
  "average": 14.375,
  "sum": 28.75,
  "rank": 2
}
404
{
  "error": "Email address not found."
}
GET
/statistics

Retrieve general statistics on recent donations, for the current user's channel. All amounts are in USD.

The donations object contains the total amount of all donations within several time periods, in hour intervals. For example, if 1436598000 was 37.02, it means $37.02 was received between 7am and 8am UTC. Any periods where 0 donations were received are excluded.

The total object contains the total amount of donations since the start of the day, week, month, year, or the all-time total.

The max object is similar to total, but the highest donation in the period is shown instead.

The average is the overall average donation amount.

Responses

200
{
  "donations": {
    "1436598000": 37.02,
    "1436608800": 74.04,
    "1436616000": 12.34,
    "1436619600": 69.79
  },
  "total": {
    "all": 193.19,
    "year": 193.19,
    "month": 193.19,
    "week": 193.19,
    "day": 193.19
  },
  "max": {
    "all": 19.15,
    "year": 19.15,
    "month": 19.15,
    "week": 19.15,
    "day": 19.15
  },
  "average": 13.8
}

Services

GET
/services/twitch

Link a Twitch account with the current user. This will give a URL to Twitch's OAuth API, which the user must be redirected to. After the user is authenticated, they will be redirected back to StreamJar, and their Twitch account will be associated with their StreamJar account.

Responses

200
{
  "link": "https://api.twitch.tv/kraken/oauth2/authorize?response_type=code&client_id=removed&redirect_uri=http://streamjar.tv/api/v1/services/twitch&scope=user_read+channel_subscriptions&state=d250723853675424d77914c400ab55ad"
}
DELETE
/services/:service

Unlink a specific service from the current StreamJar account. A successful response is returned regardless of whether a link existed.

Parameters

service

The type of service to unlink.

String (required)
Allowed values: "beam", "twitch"

Responses

200
{
  "status": true
}
400
{
  "error": "Invalid service."
}
GET
/services/beam

Link a Beam account with the current user. This will give a URL to Beam's OAuth API, which the user must be redirected to. After the user is authenticated, they will be redirected back to StreamJar, and their Twitch account will be associated with their StreamJar account.

Responses

200
{
  "link": "http://api.beam.tv/oauth/login?app_token=removed"
}
GET
/services/hitbox

Link a Hitbox account with the current user. This will give a URL to Hitbox's OAuth API, which the user must be redirected to. After the user is authenticated, they will be redirected back to StreamJar, and their Twitch account will be associated with their StreamJar account.

Responses

200
{
  "link": "http://api.hitbox.tv/oauth/login?app_token=removed"
}
GET
/services/:service/emoticons

Retrieve a list of emoticons for a particular livestreaming platform. This is useful for injecting emoticons into donation messages.

Emoticons are retrieved from <https://github.com/WatchBeam/emoticons|Beam's repository>, <https://api.twitch.tv/kraken/chat/emoticons|Twitch's API> and <https://api.smashcast.tv/chat/emotes/StreamJar|Hitbox's API>.

Parameters

service

The name of the service to retrieve emoticons for.

String (required)
Allowed values: "beam", "twitch", "hitbox"

Responses

200
[
  {
    "regex": "\:\)",
    "image": "https://streamjar.tv/api/v1/services/beam/emoticons/2764"
  }
]

Widgets

POST
/widgets

Create a new widget, which will appear on the current user's donation page.

It is important to note that each type widget has different possible fields, which you must also pass as additional parameters in your request. The acceptable types and the fields associated with them have been listed below. Some types only allow one widget of that specific type to exist on the channel.

Type Fields Duplicates allowed
text message Yes
input name, display_type, default, note No
minecraft message No
music message No

Parameters

type

The type of widget to create.

String (required)

name

The title of the new widget.

String (optional)
Default: Widget

Responses

200
{
  "id": "41ce53dd-281d-433d-ba55-d269173f759e",
  "name": "Widget",
  "type": "text",
  "data": {
    "message": "Hello"
  },
  "order": 0,
  "primary": false
}
400
{
  "error": "Invalid type."
}
400
{
  "error": "Invalid data."
}
400
{
  "error": "You cannot create a duplicate widget."
}
PATCH
/widgets

Edit a property for an existing widget.

Parameters

id

The id of the widget to edit.

String (required)

type

The type of widget to edit.

String (required)

field

The name of the field to change. All the possible fields are listed in the POST route.

String (required)

value

The new value of the field.

String (required)

Responses

200
{
  "status": true
}
400
{
  "error": "Invalid type."
}
400
{
  "error": "Invalid field."
}
404
{
  "error": "This widget does not exist."
}
DELETE
/widgets

Delete an existing widget.

Parameters

id

The id of the widget to remove.

String (required)

Responses

200
{
  "status": true
}
404
{
  "error": "This widget does not exist."
}
GET
/widgets/:id

Get a widget by it's ID

Parameters

id

The id of the widget to get.

String (required)

Responses

200
{
  "channel": "951e06ce-1f43-4db3-8668-52e64ec2db78",
  "data": {
    "default": "Default",
    "display_type": "0",
    "name": "Input",
    "note": "This is a default input.",
    "required": "false"
  },
  "id": "7d1b6496-0220-48b3-9572-18d40b666a10",
  "name": "Input",
  "order": 0,
  "primary": false,
  "type": "input"
}
404
{
  "status": false
}
PUT
/widgets

Edit a widget's properties and/or a widget's order. If you wish to change the widget's properties, you must also specify a value for each field with your parameters. If you do not specify new values for all fields, no changes will take place. A list of fields for each type of widget has been provided in the POST route.

Parameters

id

The id of the widget to edit.

String (required)

type

The type of widget to edit.

String (required)

order

The new numerical position of the widget. When widgets are displayed on the channel owner's donation page, they will be ordered based on this value. If no value is specified, the order will not be changed.

Number (optional)

Responses

200
{
  "status": true
}
400
{
  "error": "Invalid type."
}
400
{
  "error": "Invalid data."
}
400
{
  "error": "No changes made."
}
404
{
  "error": "This widget does not exist."
}

Followers

GET
/followers

Retrieve all the channel's followers. Only users who followed while the StreamJar bot is in the channel will be displayed.

Parameters

limit

The maximum number of followers to retrieve.

Number (optional)
Default: 20
Size: 1-100

page

The page of followers to retrieve, starting from 0.

Number (optional)
Default: 0

Responses

200
{
  [
    "user": 519,
    "name": "Ethan_",
    "avatar": "https://beam.pro/_latest/img/media/profile.jpg",
    "created_at": "2015-08-29T20:12:37.770Z"
  ]
}

Subscribers

GET
/subscribers

Retrieve all the channel's subscribers. Only users who subscribed while the StreamJar bot is in the channel will be displayed.

Parameters

limit

The maximum number of subscribers to retrieve.

Number (optional)
Default: 20
Size: 1-100

page

The page of subscribers to retrieve, starting from 0.

Number (optional)
Default: 0

Responses

200
{
  [
    "user": 519,
    "name": "Ethan_",
    "avatar": "https://beam.pro/_latest/img/app/avatars/default.jpg", 
    "created_at": "2015-08-29T20:12:37.770Z"
  ]
}

Keys

DELETE
/giveaway/keys

Deletes a key from the list of keys.

Parameters

id

The ID of the key you want to delete.

id (optional)

Responses

200
{
  "status": true
}
GET
/giveaway/keys

Get all keys for a giveaway.

Responses

200
{
  [
    "key": "THIS-IS-A-KEY",
    "used": false,
    "used_by": null,
    "created_at": "2015-08-29T20:12:37.770Z"
  ]
}
GET
/giveaway/keys

Get all keys for a giveaway.

Responses

200
{
  [
    "key": "THIS-IS-A-KEY",
    "used": false,
    "used_by": null,
    "created_at": "2015-08-29T20:12:37.770Z"
  ]
}
GET
/giveaway/keys

Get all keys for a giveaway.

Responses

200
{
  [
    "key": "THIS-IS-A-KEY",
    "used": false,
    "used_by": null,
    "created_at": "2015-08-29T20:12:37.770Z"
  ]
}
POST
/giveaway/keys

Creates a key for a giveaway.

Parameters

key

The key you want to add.

key (optional)

Responses

200
{
  "status": true
}

Users

GET
/users/:username?

Retrieve information on a specific user.

Parameters

username

The exact username of the account to locate. If no username is provided, the current user will be used instead.

String (optional)

Responses

200
{
  "user": {
    "username": "user",
    "display": "user",
    "current": false
  },
  "social": {
	   "twitter": "StreamJar",
    "web": "http://www.streamjar.tv/"
  },
  "services": {
    "twitch": "StreamJar",
    "beam": "StreamJar"
  },
  "widgets": [
    {
      "channel": "cc26d0e0-f0b2-4609-a49b-af39c026e085",
      "data": {
        "default": "Default",
        "display_type": "0",
        "name": "Input",
        "note": "This is a default input.",
        "required": false
      },
      "id": "d5f8955e-0c5e-49a8-8784-b04afb1fafdf",
      "name": "Input",
      "order": 0,
      "primary": false,
      "type": "input"
    }
  ]
}
404
{
  "error": "User not found."
}

Whitelist

GET
/whitelist

Retrieve all the player names of those whitelisted on the server. This endpoint will only retrieve the player names. If you require the associated donation information, please use the subscribers endpoint instead.

Responses

200
{
  [
    "Steve",
    "Alex"
  ]
}
GET
/whitelist

Retrieve all the player names of those whitelisted on the server. This endpoint will only retrieve the player names. If you require the associated donation information, please use the donations endpoint instead.

Responses

200
{
  [
    "Steve",
    "Alex"
  ]
}