Introduction

Nightbot provides a simple and extensible JSON REST API to integrate Nightbot into third party applications and services.

This API Reference will provide information on all publicly available endpoints and how to interact with them.

Errors

{
    "status": "400",
    "message": "channel is not joined"
}

Any request with a non-200 status code represents an error. We return the status as an HTTP status as well as within the response of API requests to make debugging easier.

For every error, a human-readable error message is returned under the message key. In the future, we will likely expand error handling to include error codes so that each error can be better documented and handled by third parties.

Userlevels

In order to add access levels to features of Nightbot, we use the following userlevels:

admin - Nightbot Administrator
owner - Channel Owner/Manager
moderator - Channel Moderator
twitch_vip - Twitch VIP (only for Twitch accounts)
regular - Nightbot Regular (users in the regulars list)
subscriber - Paid Channel Subscriber (called "Channel Members" on YouTube)
everyone - Normal User (default)

The userlevels are listed from highest to lowest. Users in higher userlevels acquire the permissions of the levels below them.

OAuth 2

Nightbot uses the OAuth 2 flow for securely authorizing requests to our API. Much of these authorization docs have been adapted from Google's excellent documentation on OAuth.

Basic Steps

All applications follow a basic pattern when accessing the Nightbot API using OAuth 2. At a high level, you follow four steps:

1. Obtain OAuth 2 credentials from the Nightbot Control Panel.

Visit the Nightbot Control Panel's Account Applications page to obtain OAuth 2 credentials such as a client ID and client secret that are known to both Nightbot and your application.

2. Obtain an access token from the Nightbot API.

Before your application can access private data using the Nightbot API, it must obtain an access token that grants access to the API. A single access token can grant varying degrees of access to the API. A variable parameter called scope controls the set of operations that an access token permits. During the access-token request, your application sends one or more values in the scope parameter.

There are several ways to make this request, and they vary based on the type of application you are building. For example, a server-side application might request an access token by exchanging a code redirected from our authorization endpoint, while a JavaScript application might request an access token using a browser redirect to our authorization endpoint.

Some requests require an authentication step where the user logs in with their Nightbot account (if they are not previously logged in). After logging in, the user is asked whether they are willing to grant the permissions that your application is requesting. This process is called user consent.

If the user grants the permission, the Nightbot API sends your application an access token (or an authorization code that your application can use to obtain an access token). If the user does not grant the permission, the server returns an error.

It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front.

3. Send the access token to an API.

After an application obtains an access token, it sends the token to the Nightbot API in an HTTP authorization header. It is possible to send tokens as URI query-string parameters, but we don't recommend it, because URI parameters can end up in log files that are not completely secure. Also, it is good REST practice to avoid creating unnecessary URI parameter names.

Access tokens are valid only for the set of operations and resources described in the scope of the token request.

4. Refresh the access token, if necessary.

Access tokens have limited lifetimes. If your application needs access to the Nightbot API beyond the lifetime of a single access token, it can obtain a refresh token. A refresh token allows your application to obtain new access tokens.

Scopes

We provide the following scopes to allow you to restrict Nightbot API access to use only what your application requires.

channel - View and edit channel settings and join/part the bot
channel_send - Ability to send messages to the channel as Nightbot
commands - View, add, edit, and remove channel custom commands
commands_default - View, edit, enable, and disable channel default commands
regulars - View, add, and remove channel regulars
song_requests - View and edit channel song request settings
song_requests_queue - View, add, edit, and remove songs on the channel song request queue
song_requests_playlist - View, add, edit, and remove songs on the channel song request playlist
spam_protection - View, edit, enable, and disable channel spam protection filters
subscribers - View, add, and remove channel subscribers (useful for third party subscription services)
timers - View, add, edit, and remove channel timers

Authorization Code Flow

1. Register an app

First you need to register an OAuth application on the applications page of your account area. Name your app and specify a URL users should be redirected to after authorizing your app. After creating an application, you need to generate a client secret. Click the edit button for your app on the apps page, and then click on the "New Secret" button.

2. Once you have created an app, you can 302 redirect users to our authorization endpoint:

https://api.nightbot.tv/oauth2/authorize

with the following query string parameters:

Parameter	Values	Description
`client_id`	The client ID for the app	Identifies the client that is making the request. The value passed in this parameter must exactly match the value for the app.
`redirect_uri`	One of the redirect url values listed for the app	Determines where the response is sent. The value of this parameter must exactly match one of the values listed for this app (including the http or https scheme and casing).
`response_type`	`code`	Determines whether the OAuth 2 endpoint returns an authorization code. Web server applications should use code.
`scope`	Space-delimited set of permissions that the application requests.	Identifies the access that your application is requesting. The values passed in this parameter inform the consent screen that is shown to the user. There is an inverse relationship between the number of permissions requested and the likelihood of obtaining user consent. For information about available scopes, see scopes.
`state`	Any string	Provides any state that might be useful to your application upon receipt of the response. The authorization server roundtrips this parameter, so your application receives the same value it sent. To mitigate against cross-site request forgery (CSRF), it is strongly recommended to include an anti-forgery token in the state, and confirm it in the response.

Example URL:

https://api.nightbot.tv/oauth2/authorize?response_type=code&client_id=d3cfa25e47c9c18e51220e4757d8e57a&redirect_uri=https%3A%2F%2Ftesting.com%2Fcallback&scope=commands%20timers

3. From the URL above users can choose to allow or deny your application access. Users will then be sent back to your application with a code.

Successful Response Example:

https://your_redirect_uri?code=cfbdb83aaa4d5c2534c23329de35301a

Unsuccessful Response Example:

https://your_redirect_uri?error=access_denied

4. With the authorization code sent back with the user, you can exchange it for an access token with a POST request to the following endpoint:

https://api.nightbot.tv/oauth2/token

curl -X POST "https://api.nightbot.tv/oauth2/token" \
  -d "client_id=d3cfa25e47c9c18e51220e4757d8e57a" \
  -d "client_secret=50951bf21ec9639b210c7fda38665861" \
  -d "grant_type=authorization_code" \
  -d "redirect_uri=https%3A%2F%2Ftesting.com%2Fcallback" \
  -d "code=cfbdb83aaa4d5c2534c23329de35301a"

{
  "access_token": "4fb1fed8889ec9d1c319d5b3c9a54b23",
  "refresh_token": "b98dbbc2e64789532de2c9e7c69b0f89",
  "token_type": "bearer",
  "expires_in": 2592000,
  "scope": "commands timers"
}

The request must include the following parameters:

Field	Description
`client_id`	The client ID of the app.
`client_secret`	The client secret of the app.
`code`	The authorization code returned from the initial request.
`grant_type`	As defined in the OAuth 2 specification, this field must contain a value of `authorization_code`.
`redirect_uri`	One of the redirect URIs listed for the app.

A successful response from the token endpoint will return an access token and a refresh token.

Field	Description
`access_token`	The token that can be sent to the Nightbot API.
`expires_in`	The remaining lifetime of the access token.
`refresh_token`	A token that may be used to obtain a new access token. Refresh tokens are valid until the user revokes access, they expire, or they are used.
`token_type`	Identifies the type of token returned. At this time, this field will always have the value `bearer`.
`scope`	A space separated list of scopes attached to the token returned. This should be identical to scopes requested during authorization.

5. The access token can then be used to access the Nightbot API. Access tokens last 30 days and then must be replaced either by using the refresh token flow or by reauthorizing the user with OAuth. Refresh tokens last 60 days, and a new one is issued by the refresh token flow should you choose to use it.

# Access the API via header
curl -X GET "https://api.nightbot.tv/1/me" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

# Access the API via query string
curl -X GET "https://api.nightbot.tv/1/me?access_token=4fb1fed8889ec9d1c319d5b3c9a54b23"

Accessing the API via header:

GET /1/me HTTP/1.1
Authorization: Bearer access_token
Host: api.nightbot.tv

Accessing the API via query string:

GET /1/me?access_token=access_token
Host: api.nightbot.tv

Implicit Flow

1. Register an app

First you need to register an OAuth application on the applications page of your account area. Name your app and specify a URL users should be redirected to after authorizing your app. Because this is a client-side flow, you do not need to generate or use a client secret.

2. Once you have created an app, you can 302 redirect users to our authorization endpoint:

https://api.nightbot.tv/oauth2/authorize

with the following query string parameters:

Parameter	Values	Description
`client_id`	The client ID for the app	Identifies the client that is making the request. The value passed in this parameter must exactly match the value for the app.
`redirect_uri`	One of the redirect url values listed for the app	Determines where the response is sent. The value of this parameter must exactly match one of the values listed for this app (including the http or https scheme and casing).
`response_type`	`token`	Determines whether the OAuth 2 endpoint returns a token in the fragment of the redirect url.
`scope`	Space-delimited set of permissions that the application requests.	Identifies the access that your application is requesting. The values passed in this parameter inform the consent screen that is shown to the user. There is an inverse relationship between the number of permissions requested and the likelihood of obtaining user consent. For information about available scopes, see scopes.
`state`	Any string	Provides any state that might be useful to your application upon receipt of the response. The authorization server roundtrips this parameter, so your application receives the same value it sent. To mitigate against cross-site request forgery (CSRF), it is strongly recommended to include an anti-forgery token in the state, and confirm it in the response.

Example URL:

https://api.nightbot.tv/oauth2/authorize?response_type=token&client_id=d3cfa25e47c9c18e51220e4757d8e57a&redirect_uri=https%3A%2F%2Ftesting.com%2Fcallback&scope=commands%20timers

3. From the URL above users can choose to allow or deny your application access. Users will then be sent back to your application with an access token.

Successful Response Example:

https://your_redirect_uri#access_token=cfbdb83aaa4d5c2534c23329de35301a&expires_in=2592000&token_type=bearer

Unsuccessful Response Example:

https://your_redirect_uri#error=access_denied

5. The access token can then be used to access the Nightbot API. Access tokens last 30 days and then must be replaced by reauthorizing the user with OAuth. Refresh tokens are not issued for implicit authorizations, so it is not possible to refresh the access token with this implementation.

# Access the API via header
curl -X GET "https://api.nightbot.tv/1/me" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

# Access the API via query string
curl -X GET "https://api.nightbot.tv/1/me?access_token=4fb1fed8889ec9d1c319d5b3c9a54b23"

Accessing the API via header:

GET /1/me HTTP/1.1
Authorization: Bearer access_token
Host: api.nightbot.tv

Accessing the API via query string:

GET /1/me?access_token=access_token
Host: api.nightbot.tv

Refreshing Tokens

curl -X POST "https://api.nightbot.tv/oauth2/token" \
  -d "client_id=d3cfa25e47c9c18e51220e4757d8e57a" \
  -d "client_secret=50951bf21ec9639b210c7fda38665861" \
  -d "grant_type=refresh_token" \
  -d "redirect_uri=https%3A%2F%2Ftesting.com%2Fcallback" \
  -d "refresh_token=cfbdb83aaa4d5c2534c23329de35301a"

{
  "access_token": "4fb1fed8889ec9d1c319d5b3c9a54b23",
  "refresh_token": "b98dbbc2e64789532de2c9e7c69b0f89",
  "token_type": "bearer",
  "expires_in": 2592000,
  "scope": "commands timers"
}

As indicated in the previous sections, a refresh token is obtained in the token exchange with an authorization code. In this case, your application may obtain a new access token by sending a refresh token to the token endpoint:

https://api.nightbot.tv/oauth2/token

The request must include the following parameters:

Field	Description
`client_id`	The client ID of the app.
`client_secret`	The client secret of the app.
`grant_type`	As defined in the OAuth 2 specification, this field must contain a value of `refresh_token`.
`redirect_uri`	One of the redirect URIs listed for the app.
`refresh_token`	The refresh token of the access token being refreshed.

The new access token can then be used to access the Nightbot API. Access tokens last 30 days and then must be replaced either by using the new refresh token flow or by reauthorizing the user with OAuth. Refresh tokens last 60 days.

Revoking Tokens

curl -X POST "https://api.nightbot.tv/oauth2/token/revoke" \
  -d "token=cfbdb83aaa4d5c2534c23329de35301a"

In some cases a user may wish to revoke access given to an application. A user can revoke access by visiting Account Applications. It is also possible for an application to programmatically revoke the access given to it. Programmatic revocation is important in instances where a user unsubscribes or removes an application. In other words, part of the removal process can include an API request to ensure the permissions granted to the application are removed.

To revoke an access or refresh token, pass the token in a POST request to the revocation endpoint:

https://api.nightbot.tv/oauth2/token/revoke

The request must include the following parameters:

Field	Description
`token`	The access or refresh token being revoked.

Channel

The channel endpoints allow you to get information about the channel as well as join and part the bot.

Channel Resource

Fields	Type	Description
`_id`	string	Channel ID
`displayName`	string	Channel display name
`joined`	boolean	Channel join status
`name`	string	Channel name
`plan`	string	For future use

Get channel

curl -X GET "https://api.nightbot.tv/1/channel" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200,
    "channel": {
        "_id": "567224fe9511a38f5114cae0",
        "name": "testing",
        "displayName": "Testing",
        "joined": true,
        "plan": "554eb4df3ee1bab94698bae8"
    }
}

Gets the current API user's channel information

HTTP Request

GET https://api.nightbot.tv/1/channel

Scope

channel

Join channel

curl -X POST "https://api.nightbot.tv/1/channel/join" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200
}

Makes Nightbot join (enter) the current user's channel

HTTP Request

POST https://api.nightbot.tv/1/channel/join

Scope

channel

Part channel

curl -X POST "https://api.nightbot.tv/1/channel/part" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200
}

Makes Nightbot part (leave) the current user's channel

HTTP Request

POST https://api.nightbot.tv/1/channel/part

Scope

channel

Send channel message

curl -X POST "https://api.nightbot.tv/1/channel/send" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \
  -d "message=test%20message"

{
    "status": 200
}

Makes Nightbot send a message to the channel

HTTP Request

POST https://api.nightbot.tv/1/channel/send

Scope

channel_send

Rate Limit

This endpoint is rate limited to 1 request per 5 seconds. If exceeded a HTTP 429 "Too Many Requests" response is returned.

Body Parameters

The following parameters can be sent as a URL encoded string or JSON (using the appropriate Content-Type header).

Parameter	Type	Required	Description
message	string	Required	The message to send to chat. Maximum length: 400 characters
chatId	string	Optional	The chat ID to send chat to. When not provided the message is sent to all chat rooms for this channel. This is only useful for YouTube channels with multiple concurrent chat rooms.

Commands

The commands endpoints allow you to view, add, edit, and remove channel commands. Default commands can only be enabled and disabled, not removed.

Custom Command Resource

Fields	Type	Description
`_id`	string	The command's unique ID
`coolDown`	number	The minimum amount of seconds between command usage (prevents spam)
`count`	number	The number of times a command has been used (only increments if the command uses the count variable)
`createdAt`	date	The time the command was created
`message`	string	The message Nightbot sends to chat when the command is called. It can contain variables for extra functionality.
`name`	string	The command name (usually prefixed with a !, but any prefix [or none] can be used)
`updatedAt`	date	The last time the command was updated
`userLevel`	enum	The userlevel required to use the command

Default Command Resource

Fields	Type	Description
`_name`	string	The command's unique name
`coolDown`	number	The minimum amount of seconds between command usage (prevents spam)
`enabled`	boolean	The status of the default command. If `true`, command is enabled. If `false`, the command is disabled and is nonfunctional.
`name`	string	The command name (usually prefixed with a !, but any prefix [or none] can be used)
`userLevel`	enum	The userlevel required to use the command

Get custom commands

curl -X GET "https://api.nightbot.tv/1/commands" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "_total": 30,
    "status": 200,
    "commands": [
        {
            "_id": "56739fb5d0c250946ed6746e",
            "createdAt": "2015-12-18T05:55:01.735Z",
            "updatedAt": "2015-12-18T05:55:01.735Z",
            "name": "!testing",
            "message": "this is a test message",
            "coolDown": 30,
            "count": 0,
            "userLevel": "everyone"
        },
        ...
    ]
}

Gets the current API user's custom commands list

HTTP Request

GET https://api.nightbot.tv/1/commands

Scope

commands

Add new custom command

curl -X POST "https://api.nightbot.tv/1/commands" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \
  -d "message=test%20message" \
  -d "userLevel=everyone" \
  -d "coolDown=5" \
  -d "name=!test"

{
    "status": 200,
    "command": {
        "createdAt": "2016-01-04T05:26:27.593Z",
        "updatedAt": "2016-01-04T05:26:27.593Z",
        "name": "!test",
        "message": "test message",
        "_id": "568a02834184d1a07660f380",
        "coolDown": 5,
        "count": 0,
        "userLevel": "everyone"
    }
}

Adds a new custom command to the current user's channel

HTTP Request

POST https://api.nightbot.tv/1/commands

Scope

commands

Body Parameters

The following parameters can be sent as a URL encoded string or JSON (using the appropriate Content-Type header).

Parameter	Type	Required	Description
coolDown	number	Required	The minimum amount of seconds between command usage (prevents spam).
message	string	Required	The message to send to chat. It can contain variables for extra functionality. Maximum length: 400 characters
name	string	Required	The command name (usually prefixed with a !, but any prefix [or none] can be used)
userLevel	enum	Required	The userlevel required to use the command.

Get custom command by id

curl -X GET "https://api.nightbot.tv/1/commands/56739fb5d0c250946ed6746e" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200,
    "command": {
        "_id": "56739fb5d0c250946ed6746e",
        "createdAt": "2015-12-18T05:55:01.735Z",
        "updatedAt": "2015-12-18T05:55:01.735Z",
        "name": "!testing",
        "message": "this is a test message",
        "coolDown": 30,
        "count": 0,
        "userLevel": "everyone"
    }
}

Looks up a custom command by id

HTTP Request

GET https://api.nightbot.tv/1/commands/:id

Scope

commands

Edit custom command by id

curl -X PUT "https://api.nightbot.tv/1/commands/568a02834184d1a07660f380" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \
  -d "name=!testing"

{
    "status": 200,
    "command": {
        "createdAt": "2016-01-04T05:26:27.593Z",
        "updatedAt": "2016-01-04T05:26:27.593Z",
        "name": "!testing",
        "message": "test message",
        "_id": "568a02834184d1a07660f380",
        "coolDown": 5,
        "count": 0,
        "userLevel": "everyone"
    }
}

Edits a custom command by its id.

HTTP Request

PUT https://api.nightbot.tv/1/commands/:id

Scope

commands

Body Parameters

The following parameters can be sent as a URL encoded string or JSON (using the appropriate Content-Type header). PUT requests usually require the entire model to be included in the request, but we allow partial updates.

Parameter	Type	Required	Description
coolDown	number	Optional	The minimum amount of seconds between command usage (prevents spam). Defaults to `30`
count	number	Optional	The number of times a command has been used (only increments if the command uses the count variable). Defaults to `0`
message	string	Optional	The message to send to chat. It can contain variables for extra functionality. Maximum length: 400 characters
name	string	Optional	The command name (usually prefixed with a !, but any prefix [or none] can be used)
userLevel	enum	Optional	The userlevel required to use the command. Defaults to `everyone`

Delete custom command by id

curl -X DELETE "https://api.nightbot.tv/1/commands/56739fb5d0c250946ed6746e" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200
}

Deletes a custom command by id

HTTP Request

DELETE https://api.nightbot.tv/1/commands/:id

Scope

commands

Get default commands

curl -X GET "https://api.nightbot.tv/1/commands/default" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "_total": 8,
    "status": 200,
    "commands": [
        {
            "name": "!commands",
            "coolDown": 5,
            "enabled": true,
            "userLevel": "everyone",
            "_name": "commands",
            "_description": "Allows users to get a list of commands and moderators to manage commands",
            "_docs": "https://docs.nightbot.tv/commands/commands"
        },
        ...
    ]
}

Gets the current API user's default commands list

HTTP Request

GET https://api.nightbot.tv/1/commands/default

Scope

commands_default

Get default command by name

curl -X GET "https://api.nightbot.tv/1/commands/default/commands" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200,
    "command": {
        "name": "!commands",
        "coolDown": 5,
        "enabled": true,
        "userLevel": "everyone",
        "_name": "commands",
        "_description": "Allows users to get a list of commands and moderators to manage commands",
        "_docs": "https://docs.nightbot.tv/commands/commands"
    }
}

Looks up a default command by name

HTTP Request

GET https://api.nightbot.tv/1/commands/default/:name

Scope

commands_default

Edit default command by name

curl -X PUT "https://api.nightbot.tv/1/commands/default/commands" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \
  -d "coolDown=6"

{
    "status": 200,
    "command": {
        "name": "!commands",
        "coolDown": 6,
        "enabled": true,
        "userLevel": "everyone",
        "_name": "commands",
        "_description": "Allows users to get a list of commands and moderators to manage commands",
        "_docs": "https://docs.nightbot.tv/commands/commands"
    }
}

Edits a default command by its name.

HTTP Request

PUT https://api.nightbot.tv/1/commands/default/:name

Scope

commands_default

Body Parameters

Parameter	Type	Required	Description
coolDown	number	Optional	The minimum amount of seconds between command usage (prevents spam).
enabled	boolean	Optional	The status of the default command. If `true`, command is enabled. If `false`, the command is disabled and is nonfunctional.
userLevel	enum	Optional	The userlevel required to use the command.

Me

The me endpoint provides you with information about the authorized user

Authorization Resource

Fields	Type	Description
`userLevel`	enum	Used internally. Always `owner` for oauth2.
`authType`	enum	Used internally. Always `oauth2` for oauth2.
`credentials`	object	Contains access token `expires` as a date and `client` id as a string (of the app the current access token belongs to)
`scopes`	array	Array of scopes this authorization grants access to

User Resource

Fields	Type	Description
`_id`	string	User id
`admin`	boolean	Whether or not the user is a Nightbot administrator
`avatar`	string	User avatar link
`displayName`	string	User display name
`name`	string	User name
`provider`	enum	The auth provider for the user account (like `twitch` or `youtube`)
`providerId`	string	The unique id for this user at the auth provider

Get current user

curl -X GET "https://api.nightbot.tv/1/me" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
  "status": 200,
  "authorization": {
    "userLevel": "owner",
    "authType": "oauth2",
    "credentials": {
      "expires": "2016-02-02T20:32:36.129Z",
      "client": "d3cfa25e47c9c18e51220e4757d8e57a"
    },
    "scopes": [
      "channel",
      "channel_send",
      "commands",
      "commands_default",
      "logs",
      "regulars",
      "song_requests",
      "song_requests_queue",
      "song_requests_playlist",
      "spam_protection",
      "timers"
    ]
  },
  "user": {
    "_id": "567224fe9511a38f5114cae0",
    "name": "testing",
    "displayName": "Testing",
    "provider": "twitch",
    "providerId": "24895647",
    "avatar": "https://static-cdn.jtvnw.net/jtv_user_pictures/testing-profile_image-b209b2800a897689-300x300.png",
    "admin": false
  }
}

Gets the current API user's information

HTTP Request

GET https://api.nightbot.tv/1/me

Scope

none required

Regulars

The regulars endpoints allow you to view, add, edit, and remove channel regulars. Nightbot Regulars adds another userlevel to the chat. Regulars can be granted extra permission for commands and spam protection.

Regular Resource

Fields	Type	Description
`_id`	string	Regular id
`createdAt`	date	The time the regular was added
`displayName`	string	User display name
`name`	string	User unique name
`provider`	enum	The auth provider for the regular (like `twitch` or `youtube`)
`providerId`	string	The unique id for this user at the auth provider
`updatedAt`	date	The last time the regular was updated

Get regulars

curl -X GET "https://api.nightbot.tv/1/regulars" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "_total": 30,
    "status": 200,
    "regulars": [
        {
            "_id": "56739fb5d0c250946ed67448",
            "createdAt": "2015-12-18T05:55:01.458Z",
            "updatedAt": "2015-12-18T05:55:01.458Z",
            "provider": "twitch",
            "providerId": "96837452",
            "name": "test_user",
            "displayName": "Test_User"
        },
        ...
    ]
}

Gets the current API user's regulars list

HTTP Request

GET https://api.nightbot.tv/1/regulars

Scope

regulars

Query String Parameters

Parameter	Type	Required	Description
limit	number	Optional	The is the maximum amount of regulars to return in the request (minimum 1, maximum 100)
offset	number	Optional	This is the regular offset count that is used for pagination
q	string	Optional	A `displayName` to search for (case insensitive)

Add new regular

curl -X POST "https://api.nightbot.tv/1/regulars" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \
  -d "name=test_user"

{
    "status": 200,
    "regular": {
        "_id": "56739fb5d0c250946ed67448",
        "createdAt": "2015-12-18T05:55:01.458Z",
        "updatedAt": "2015-12-18T05:55:01.458Z",
        "provider": "twitch",
        "providerId": "96837452",
        "name": "test_user",
        "displayName": "Test_User"
    }
}

Adds a new regular to the current user's channel

HTTP Request

POST https://api.nightbot.tv/1/regulars

Scope

regulars

Body Parameters

The following parameters can be sent as a URL encoded string or JSON (using the appropriate Content-Type header).

Parameter	Type	Required	Description
name	string	Required	This is the username of the person you wish to add as a regular. In the case of YouTube, it would be the user's YouTube channel URL.

Get regular by id

curl -X GET "https://api.nightbot.tv/1/regulars/56739fb5d0c250946ed67448" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200,
    "regular": {
        "_id": "56739fb5d0c250946ed67448",
        "createdAt": "2015-12-18T05:55:01.458Z",
        "updatedAt": "2015-12-18T05:55:01.458Z",
        "provider": "twitch",
        "providerId": "96837452",
        "name": "test_user",
        "displayName": "Test_User"
    }
}

Looks up a regular by id

HTTP Request

GET https://api.nightbot.tv/1/regulars/:id

Scope

regulars

Delete regular by id

curl -X DELETE "https://api.nightbot.tv/1/regulars/56739fb5d0c250946ed67448" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200
}

Deletes a regular by id

HTTP Request

DELETE https://api.nightbot.tv/1/regulars/:id

Scope

regulars

Song Requests

The song request endpoints allow you to view, add, edit, and delete song from the song request queue and playlist as well as modify the settings for song requests.

Song Request Settings Resource

Fields	Type	Description
`enabled`	boolean	The status of song requests. If `true`, song requests are enabled and songs can be requested by users. If `false`, song requests are disabled and are nonfunctional.
`limits`	object	Contains user-configurable song request limits
`limits` `.queue`	number	The maximum number of songs in the queue (minimum 1, maximum 100)
`limits` `.user`	number	The maximum number of songs a user can request at a time (minimum 1, maximum 100)
`limits` `.playlistOnly`	boolean	If `true`, song requests will be limited to the configured `playlist`. If `false`, requests can be made from any listed `providers`
`limits` `.exemptUserLevel`	enum	The userlevel required to be exempt from the limits
`playlist`	enum	The playlist AutoDJ will source from when the queue is empty. If `limits.playlistOnly` is `true` all requested songs must be on this playlist. Available playlists are listed in the song request settings GET endpoint as `playlists`.
`providers`	array	An array of enums for the enabled song request providers. Providers are the services which we support pulling songs from. Available providers are listed in the song request settings GET endpoint as `providers`.
`searchProvider`	enum	Instead of requiring users to request songs with a URL or ID, users can search for the closest match to request a song. This controls where that search is performed. Available providers are listed in the song request settings GET endpoint as `providers`.
`userLevel`	enum	The userlevel required to be able to request songs
`volume`	number	The volume that the AutoDJ player runs at (minimum 0, maximum 100)
`youtube`	object	YouTube-specific song request settings
`youtube` `.limitToMusic`	boolean	To reduce non-music videos from being requested, you can limit to just the music category by setting this to `true`. If set to `false`, videos are not restricted to just the music category.
`youtube` `.limitToLikedVideos`	boolean	To reduce bad videos from being requested, you can limit to videos with more likes than dislikes by setting this to `true`. If set to `false`, videos with more dislikes than likes are able to be requested. Defaults to `true`

Playlist Item Resource

Fields	Type	Description
`_id`	string	The playlist item's unique id
`createdAt`	date	The time the playlist item was created
`track`	object	Track Information
`track` `.artist`	string, optional	Track Artist
`track` `.duration`	number	Track Duration (in seconds)
`track` `.provider`	enum	Track Provider (like "youtube" or "soundcloud")
`track` `.providerId`	string	Track Provider's unique id
`track` `.title`	string	Track Title
`track` `.url`	string	Track URL
`updatedAt`	date	The last time the playlist item was updated

Queue Item Resource

Fields	Type	Description
`_position`	number, optional	The queue item's position in the queue
`_id`	string	The queue item's unique id
`createdAt`	date	The time the queue item was created
`track`	object	Track Information
`track` `.artist`	string, optional	Track Artist
`track` `.duration`	number	Track Duration (in seconds)
`track` `.provider`	enum	Track Provider (like "youtube" or "soundcloud")
`track` `.providerId`	string	Track Provider's unique id
`track` `.title`	string	Track Title
`track` `.url`	string	Track URL
`user`	object	Information about who the queue item belongs to
`user` `.displayName`	string	User display name
`user` `.name`	string	User unique name
`user` `.provider`	enum	User provider (like "twitch" or "youtube")
`user` `.providerId`	string	User provider's unique id
`updatedAt`	date	The last time the queue item was updated

Get song request settings

curl -X GET "https://api.nightbot.tv/1/song_requests" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200,
    "settings": {
        "limits": {
            "queue": 20,
            "user": 10,
            "playlistOnly": false,
            "exemptUserLevel": "moderator"
        },
        "volume": 59,
        "enabled": true,
        "providers": [
            "soundcloud",
            "youtube"
        ],
        "playlist": "channel",
        "userLevel": "everyone",
        "searchProvider": "soundcloud",
        "youtube": {
            "limitToMusic": false,
            "limitToLikedVideos": true
        }
    },
    "providers": {
        "soundcloud": "SoundCloud",
        "youtube": "YouTube"
    },
    "playlists": {
        "channel": "Channel",
        "monstercat": "Monstercat",
        "twitch_music_library": "Twitch Music Library"
    }
}

Gets the current API user's song request settings

HTTP Request

GET https://api.nightbot.tv/1/song_requests

Scope

song_requests

Edit song request settings

curl -X PUT "https://api.nightbot.tv/1/song_requests" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \
  -d "enabled=false"

{
    "status": 200,
    "settings": {
        "youtube": {
            "limitToMusic": false,
            "limitToLikedVideos": true
        },
        "searchProvider": "soundcloud",
        "userLevel": "everyone",
        "playlist": "channel",
        "providers": ["soundcloud", "youtube"],
        "enabled": false,
        "volume": 59,
        "limits": {
            "queue": 20,
            "user": 10,
            "playlistOnly": false,
            "exemptUserLevel": "moderator"
        }
    },
    "providers": {
        "soundcloud": "SoundCloud",
        "youtube": "YouTube"
    },
    "playlists": {
        "channel": "Channel",
        "monstercat": "Monstercat",
        "twitch_music_library": "Twitch Music Library"
    }
}

Edits the song request settings

HTTP Request

PUT https://api.nightbot.tv/1/song_requests

Scope

song_requests

Body Parameters

Parameter	Type	Required	Description
enabled	boolean	Optional	The status of song requests. If `true`, song requests are enabled and songs can be requested by users. If `false`, song requests are disabled and are nonfunctional.
limits .queue	number	Optional	The maximum number of songs in the queue (minimum 1, maximum 100)
limits .user	number	Optional	The maximum number of songs a user can request at a time (minimum 1, maximum 100)
limits .playlistOnly	boolean	Optional	If `true`, song requests will be limited to the configured `playlist`. If `false`, requests can be made from any listed `providers`
limits .playlistOnly	boolean	Optional	If `true`, song requests will be limited to the configured `playlist`. If `false`, requests can be made from any listed `providers`
limits .exemptUserLevel	enum	Optional	The userlevel required to be exempt from the limits
playlist	enum	Optional	The playlist AutoDJ will source from when the queue is empty. If `limits.playlistOnly` is `true` all requested songs must be on this playlist. Available playlists are listed in the song request settings GET endpoint as `playlists`.
providers	array	Optional	An array of enums for the enabled song request providers. Providers are the services which we support pulling songs from. Available providers are listed in the song request settings GET endpoint as `providers`.
searchProvider	enum	Optional	Instead of requiring users to request songs with a URL or ID, users can search for the closest match to request a song. This controls where that search is performed. Available providers are listed in the song request settings GET endpoint as `providers`.
userLevel	enum	Optional	The userlevel required to be able to request songs
volume	number	Optional	The volume that the AutoDJ player runs at (minimum 0, maximum 100)
youtube .limitToMusic	boolean	Optional	To reduce non-music videos from being requested, you can limit to just the music category by setting this to `true`. If set to `false`, videos are not restricted to just the music category.
youtube .limitToLikedVideos	boolean	Optional	To reduce bad videos from being requested, you can limit to videos with more likes than dislikes by setting this to `true`. If set to `false`, videos with more dislikes than likes are able to be requested. Defaults to `true`

Get playlist

curl -X GET "https://api.nightbot.tv/1/song_requests/playlist" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200,
    "_sort": {
        "date": "asc"
    },
    "_limit": 25,
    "_offset": 0,
    "_total": 34,
    "playlist": [
        {
            "track": {
                "providerId": "njos57IJf-0",
                "provider": "youtube",
                "duration": 168,
                "title": "Steve Jobs vs Bill Gates.  Epic Rap Battles of History Season 2.",
                "artist": "ERB",
                "url": "https://youtu.be/njos57IJf-0"
            },
            "_id": "567baac77aa5ea140225baec",
            "createdAt": "2015-12-24T08:20:23.268Z",
            "updatedAt": "2015-12-24T08:20:23.268Z"
        },
        ...
    ]
}

Gets the current API user's song request playlist

HTTP Request

GET https://api.nightbot.tv/1/song_requests/playlist

Scope

song_requests_playlist

Query String Parameters

Parameter	Type	Required	Description
direction	enum	Optional	This is the sorting direction. Values are `asc` or `desc`
limit	number	Optional	The is the maximum amount of playlist items to return in the request (minimum 1, maximum 100)
offset	number	Optional	This is the playlist item offset count that is used for pagination
q	string	Optional	A term to search for (case insensitive)
sort_by	enum	Optional	This is the sorting selection. Values are `artist`, `date`, `random`, `title`. Defaults to `date`.

Add new playlist item

curl -X POST "https://api.nightbot.tv/1/song_requests/playlist" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \
  -d "q=https%3A%2F%2Fyoutu.be%2FN9qYF9DZPdw"

{
    "status": 200,
    "item": {
        "track": {
            "providerId": "N9qYF9DZPdw",
            "provider": "youtube",
            "duration": 171,
            "title": "\"Weird Al\" Yankovic - White & Nerdy (Official Video)",
            "artist": "alyankovicVEVO",
            "url": "https://youtu.be/N9qYF9DZPdw"
        },
        "_id": "567baac77aa5ea140225baf0",
        "createdAt": "2015-12-24T08:20:23.268Z",
        "updatedAt": "2015-12-24T08:20:23.268Z"
    }
}

Adds a new playlist item to the current user's channel.

HTTP Request

POST https://api.nightbot.tv/1/song_requests/playlist

Scope

song_requests_playlist

Body Parameters

The following parameters can be sent as a URL encoded string or JSON (using the appropriate Content-Type header).

Parameter	Type	Required	Description
q	string	Required	This is the song to add to the playlist. It can be a URL for one of the supported song request providers or a song name to search for (closest match is chosen and search is performed on the channel's selected search provider)

Clear playlist

curl -X DELETE "https://api.nightbot.tv/1/song_requests/playlist" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200
}

Deletes all playlist items

HTTP Request

DELETE https://api.nightbot.tv/1/song_requests/playlist

Scope

song_requests_playlist

Import remote playlist

curl -X POST "https://api.nightbot.tv/1/song_requests/playlist/import" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \
  -d "url=https%3A%2F%2Fwww.youtube.com%2Fplaylist%3Flist%3DPLA11538113C16891A"

{
    "status": 200
}

Imports a remote playlist to the current user's channel.

HTTP Request

POST https://api.nightbot.tv/1/song_requests/playlist/import

Scope

song_requests_playlist

Body Parameters

The following parameters can be sent as a URL encoded string or JSON (using the appropriate Content-Type header).

Parameter	Type	Required	Description
url	string	Required	This is the playlist to import. This is a playlist URL located at one of the supported song request providers

Get playlist item by id

curl -X GET "https://api.nightbot.tv/1/song_requests/playlist/567baac77aa5ea140225baf0" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200,
    "item": {
        "track": {
            "providerId": "N9qYF9DZPdw",
            "provider": "youtube",
            "duration": 171,
            "title": "\"Weird Al\" Yankovic - White & Nerdy (Official Video)",
            "artist": "alyankovicVEVO",
            "url": "https://youtu.be/N9qYF9DZPdw"
        },
        "_id": "567baac77aa5ea140225baf0",
        "createdAt": "2015-12-24T08:20:23.268Z",
        "updatedAt": "2015-12-24T08:20:23.268Z"
    }
}

Looks up a song request playlist item by id

HTTP Request

GET https://api.nightbot.tv/1/song_requests/playlist/:id

Scope

song_requests_playlist

Delete playlist item by id

curl -X DELETE "https://api.nightbot.tv/1/song_requests/playlist/567baac77aa5ea140225baf0" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200
}

Deletes a song requests playlist item by id

HTTP Request

DELETE https://api.nightbot.tv/1/song_requests/playlist/:id

Scope

song_requests_playlist

Get queue

curl -X GET "https://api.nightbot.tv/1/song_requests/queue" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
  "_total": 1,
  "_currentSong": {
    "_id": "56888945f788ea622d320c38",
    "createdAt": "2016-01-03T02:36:53.141Z",
    "updatedAt": "2016-01-05T07:39:10.710Z",
    "track": {
      "providerId": "v4Za061pQac",
      "provider": "youtube",
      "duration": 191,
      "title": "Alex Skrindo - Jumbo [NCS Release]",
      "artist": "NoCopyrightSounds",
      "url": "https://youtu.be/v4Za061pQac"
    },
    "user": {
      "name": "test_user_1",
      "displayName": "test_user_1",
      "providerId": "94385764",
      "provider": "twitch"
    }
  },
  "_requestsEnabled": true,
  "_searchProvider": "youtube",
  "_providers": ["soundcloud", "youtube"],
  "status": 200,
  "queue": [
    {
      "_id": "5688d2bdc93762323f402b9d",
      "createdAt": "2016-01-03T07:50:21.334Z",
      "updatedAt": "2016-01-03T07:50:21.334Z",
      "track": {
        "providerId": "r9gz0Z9yV1k",
        "provider": "youtube",
        "duration": 197,
        "title": "I'm Just a Kid - Simple Plan lyrics",
        "artist": "sabrina01021997",
        "url": "https://youtu.be/r9gz0Z9yV1k"
      },
      "user": {
        "name": "test_user_2",
        "displayName": "test_user_2",
        "providerId": "93854453",
        "provider": "twitch"
      },
      "_position": 1
    }
  ]
}

Gets the current API user's song request queue

HTTP Request

GET https://api.nightbot.tv/1/song_requests/queue

Scope

song_requests_queue

Add new queue item

curl -X POST "https://api.nightbot.tv/1/song_requests/queue" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \
  -d "q=https%3A%2F%2Fyoutu.be%2Fr9gz0Z9yV1k"

{
    "status": 200,
    "item": {
        "_id": "5688d2bdc93762323f402b9d",
        "createdAt": "2016-01-03T07:50:21.334Z",
        "updatedAt": "2016-01-03T07:50:21.334Z",
        "track": {
            "providerId": "r9gz0Z9yV1k",
            "provider": "youtube",
            "duration": 197,
            "title": "I'm Just a Kid - Simple Plan lyrics",
            "artist": "sabrina01021997",
            "url": "https://youtu.be/r9gz0Z9yV1k"
        },
        "user": {
            "name": "test_user_2",
            "displayName": "test_user_2",
            "providerId": "93854453",
            "provider": "twitch"
        },
        "_position": 1
    }
}

Adds a new queue item to the current user's channel.

HTTP Request

POST https://api.nightbot.tv/1/song_requests/queue

Scope

song_requests_queue

Body Parameters

The following parameters can be sent as a URL encoded string or JSON (using the appropriate Content-Type header).

Parameter	Type	Required	Description
q	string	Required	This is the song to add to the queue. It can be a URL for one of the supported song request providers or a song name to search for (closest match is chosen and search is performed on the channel's selected search provider)

Clear queue

curl -X DELETE "https://api.nightbot.tv/1/song_requests/queue" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200
}

Deletes all queue items

HTTP Request

DELETE https://api.nightbot.tv/1/song_requests/queue

Scope

song_requests_queue

Resume current queue item

curl -X POST "https://api.nightbot.tv/1/song_requests/queue/play" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200,
    "item": {
        "_id": "5688d2bdc93762323f402b9d",
        "createdAt": "2016-01-03T07:50:21.334Z",
        "updatedAt": "2016-01-03T07:50:21.334Z",
        "track": {
            "providerId": "r9gz0Z9yV1k",
            "provider": "youtube",
            "duration": 197,
            "title": "I'm Just a Kid - Simple Plan lyrics",
            "artist": "sabrina01021997",
            "url": "https://youtu.be/r9gz0Z9yV1k"
        },
        "user": {
            "name": "test_user_2",
            "displayName": "test_user_2",
            "providerId": "93854453",
            "provider": "twitch"
        }
    }
}

Resumes the current playing queue item in the current user's channel.

HTTP Request

POST https://api.nightbot.tv/1/song_requests/queue/play

Scope

song_requests_queue

Pause current queue item

curl -X POST "https://api.nightbot.tv/1/song_requests/queue/pause" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200,
    "item": {
        "_id": "5688d2bdc93762323f402b9d",
        "createdAt": "2016-01-03T07:50:21.334Z",
        "updatedAt": "2016-01-03T07:50:21.334Z",
        "track": {
            "providerId": "r9gz0Z9yV1k",
            "provider": "youtube",
            "duration": 197,
            "title": "I'm Just a Kid - Simple Plan lyrics",
            "artist": "sabrina01021997",
            "url": "https://youtu.be/r9gz0Z9yV1k"
        },
        "user": {
            "name": "test_user_2",
            "displayName": "test_user_2",
            "providerId": "93854453",
            "provider": "twitch"
        }
    }
}

Pauses the current playing queue item in the current user's channel.

HTTP Request

POST https://api.nightbot.tv/1/song_requests/queue/pause

Scope

song_requests_queue

Skip current queue item

curl -X POST "https://api.nightbot.tv/1/song_requests/queue/skip" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200,
    "item": {
        "_id": "5688d2bdc93762323f402b9d",
        "createdAt": "2016-01-03T07:50:21.334Z",
        "updatedAt": "2016-01-03T07:50:21.334Z",
        "track": {
            "providerId": "r9gz0Z9yV1k",
            "provider": "youtube",
            "duration": 197,
            "title": "I'm Just a Kid - Simple Plan lyrics",
            "artist": "sabrina01021997",
            "url": "https://youtu.be/r9gz0Z9yV1k"
        },
        "user": {
            "name": "test_user_2",
            "displayName": "test_user_2",
            "providerId": "93854453",
            "provider": "twitch"
        }
    }
}

Skips the current playing queue item in the current user's channel.

HTTP Request

POST https://api.nightbot.tv/1/song_requests/queue/skip

Scope

song_requests_queue

Get queue item by id

curl -X GET "https://api.nightbot.tv/1/song_requests/queue/567baac77aa5ea140225baf0" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200,
    "item": {
        "_id": "5688d2bdc93762323f402b9d",
        "createdAt": "2016-01-03T07:50:21.334Z",
        "updatedAt": "2016-01-03T07:50:21.334Z",
        "track": {
            "providerId": "r9gz0Z9yV1k",
            "provider": "youtube",
            "duration": 197,
            "title": "I'm Just a Kid - Simple Plan lyrics",
            "artist": "sabrina01021997",
            "url": "https://youtu.be/r9gz0Z9yV1k"
        },
        "user": {
            "name": "test_user_2",
            "displayName": "test_user_2",
            "providerId": "93854453",
            "provider": "twitch"
        },
        "_position": 1
    }
}

Looks up a song request queue item by id

HTTP Request

GET https://api.nightbot.tv/1/song_requests/queue/:id

Scope

song_requests_queue

Delete queue item by id

curl -X DELETE "https://api.nightbot.tv/1/song_requests/queue/567baac77aa5ea140225baf0" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200
}

Deletes a song requests queue item by id

HTTP Request

DELETE https://api.nightbot.tv/1/song_requests/queue/:id

Scope

song_requests_queue

Promote queue item

curl -X POST "https://api.nightbot.tv/1/song_requests/queue/5688d2bdc93762323f402b9d/promote" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200,
    "item": {
        "_id": "5688d2bdc93762323f402b9d",
        "createdAt": "2016-01-03T07:50:21.334Z",
        "updatedAt": "2016-01-03T07:50:21.334Z",
        "track": {
            "providerId": "r9gz0Z9yV1k",
            "provider": "youtube",
            "duration": 197,
            "title": "I'm Just a Kid - Simple Plan lyrics",
            "artist": "sabrina01021997",
            "url": "https://youtu.be/r9gz0Z9yV1k"
        },
        "user": {
            "name": "test_user_2",
            "displayName": "test_user_2",
            "providerId": "93854453",
            "provider": "twitch"
        },
        "_position": 1
    }
}

Promotes a queue item to the front of the queue

HTTP Request

POST https://api.nightbot.tv/1/song_requests/queue/:id/promote

Scope

song_requests_queue

Spam Protection

The spam protection endpoints allow you to view, edit, enable, and disable spam protection filters.

Filter Resource

Fields	Type	Description
`_limitMin`	number, optional	If the filter contains a limit option, this defines its minimum value
`_limitMax`	number, optional	If the filter contains a limit option, this defines its maximum value
`_name`	string	The spam protection filter name
`_type`	enum	The spam protection filter type
`blacklist`	string, optional	New-line delimited list of blacklisted phrases. Wildcards can be used (`*`). RegEx is also supported (`~/[pattern]/[flags]`). Only can be used with filters supporting a blacklist.
`enabled`	boolean	The status of the filter. If `true`, the filter is enabled. If `false`, the filter is disabled and is nonfunctional.
`exemptUserLevel`	enum	The userlevel required to exempt from the filter
`length`	number	The length of time in seconds that Nightbot will timeout users for if detected by the filter
`limit`	number, optional	The barrier at which the filter should timeout users, should the filter have one.
`message`	string	The timeout message given to a user when they are timed out (if filter is not silenced). If empty string, defaults to Duke Nukem quotes.
`silent`	boolean	If `true`, the filter will not emit a message to chat telling to user why they were timed out. If `false`, the filter is will emit a message.
`whitelist`	string, optional	New-line delimited list of whitelisted phrases. For the link whitelist this parses hostnames (like `youtube.com` unless wildcards or regex is used). Wildcards can be used (`*`). RegEx is also supported (`~/[pattern]/[flags]`). Only can be used with filters supporting a whitelist.

Get filters

curl -X GET "https://api.nightbot.tv/1/spam_protection" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200,
    "filters": [
        {
            "enabled": true,
            "length": 600,
            "blacklist": "◕_◕*\nᴘɪᴢᴢᴀ\nˢʷᵉᵃʳ",
            "message": "",
            "silent": false,
            "exemptUserLevel": "subscriber",
            "_type": "blacklist",
            "_name": "Blacklist Words/Phrases",
            "_description": "This filter allows you to timeout custom words, phrases, and patterns.",
            "_docs": "https://docs.nightbot.tv/spam-protection/blacklist"
        },
        ...
    ]
}

Gets the current API user's spam protection filters list

HTTP Request

GET https://api.nightbot.tv/1/spam_protection

Scope

spam_protection

Get filter by type

curl -X GET "https://api.nightbot.tv/1/spam_protection/blacklist" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200,
    "filter": {
        "enabled": true,
        "length": 600,
        "blacklist": "◕_◕*\nᴘɪᴢᴢᴀ\nˢʷᵉᵃʳ",
        "message": "",
        "silent": false,
        "exemptUserLevel": "subscriber",
        "_type": "blacklist",
        "_name": "Blacklist Words/Phrases",
        "_description": "This filter allows you to timeout custom words, phrases, and patterns.",
        "_docs": "https://docs.nightbot.tv/spam-protection/blacklist"
    }
}

Looks up a spam protection filter by type

HTTP Request

GET https://api.nightbot.tv/1/spam_protection/:type

Scope

spam_protection

Edit filter by type

curl -X PUT "https://api.nightbot.tv/1/spam_protection/blacklist" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \
  -d "message=testing"

{
    "status": 200,
    "filter": {
        "enabled": true,
        "length": 600,
        "blacklist": "◕_◕*\nᴘɪᴢᴢᴀ\nˢʷᵉᵃʳ",
        "message": "testing",
        "silent": false,
        "exemptUserLevel": "subscriber",
        "_type": "blacklist",
        "_name": "Blacklist Words/Phrases",
        "_description": "This filter allows you to timeout custom words, phrases, and patterns.",
        "_docs": "https://docs.nightbot.tv/spam-protection/blacklist"
    }
}

Edits a spam protection filter by its type.

HTTP Request

PUT https://api.nightbot.tv/1/spam_protection/:type

Scope

spam_protection

Body Parameters

Parameter	Type	Required	Description
blacklist	string	Optional	New-line delimited list of blacklisted phrases. Wildcards can be used (`*`). RegEx is also supported (`~/[pattern]/[flags]`). Only can be used with filters supporting a blacklist.
enabled	boolean	Optional	The status of the filter. If `true`, the filter is enabled. If `false`, the filter is disabled and is nonfunctional.
exemptUserLevel	enum	Optional	The userlevel required to exempt from the filter
length	number	Optional	The length of time in seconds that Nightbot will timeout users for if detected by the filter
limit	number	Optional	The barrier at which the filter should timeout users, should the filter have one. Only can be used with filters supporting a limit.
message	string	Optional	The timeout message given to a user when they are timed out (if filter is not silenced). If empty string, defaults to Duke Nukem quotes.
silent	boolean	Optional	If `true`, the filter will not emit a message to chat telling to user why they were timed out. If `false`, the filter is will emit a message.
whitelist	string	Optional	New-line delimited list of whitelisted phrases. For the link whitelist this parses hostnames (like `youtube.com` unless wildcards or regex is used). Wildcards can be used (`*`). RegEx is also supported (`~/[pattern]/[flags]`). Only can be used with filters supporting a whitelist.

Subscribers

The subscribers endpoints allow you to view, add, edit, and remove channel subscribers. Subscribers can be granted extra permission for commands and spam protection.

This subscribers list complements any existing paid subscription service already existing. Twitch/YouTube only give paid subscription programs to some of the broadcasters, leaving many users without a subscription program. Other third party platforms may offer subscription services that offset the need for a subscription program for these affected users.

Subscriber Resource

Fields	Type	Description
`_id`	string	subscriber id
`createdAt`	date	The time the subscriber was added
`displayName`	string	User display name
`name`	string	User unique name
`provider`	enum	The auth provider for the subscriber (like `twitch` or `youtube`)
`providerId`	string	The unique id for this user at the auth provider
`updatedAt`	date	The last time the subscriber was updated

Get subscribers

curl -X GET "https://api.nightbot.tv/1/subscribers" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "_total": 30,
    "status": 200,
    "subscribers": [
        {
            "_id": "56739fb5d0c250946ed67448",
            "createdAt": "2015-12-18T05:55:01.458Z",
            "updatedAt": "2015-12-18T05:55:01.458Z",
            "provider": "twitch",
            "providerId": "96837452",
            "name": "test_user",
            "displayName": "Test_User"
        },
        ...
    ]
}

Gets the current API user's subscribers list

HTTP Request

GET https://api.nightbot.tv/1/subscribers

Scope

subscribers

Query String Parameters

Parameter	Type	Required	Description
limit	number	Optional	The is the maximum amount of subscribers to return in the request (minimum 1, maximum 100)
offset	number	Optional	This is the subscriber offset count that is used for pagination
q	string	Optional	A `displayName` to search for (case insensitive)

Add new subscriber

curl -X POST "https://api.nightbot.tv/1/subscribers" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \
  -d "name=test_user"

{
    "status": 200,
    "subscriber": {
        "_id": "56739fb5d0c250946ed67448",
        "createdAt": "2015-12-18T05:55:01.458Z",
        "updatedAt": "2015-12-18T05:55:01.458Z",
        "provider": "twitch",
        "providerId": "96837452",
        "name": "test_user",
        "displayName": "Test_User"
    }
}

Adds a new subscriber to the current user's channel

HTTP Request

POST https://api.nightbot.tv/1/subscribers

Scope

subscribers

Body Parameters

The following parameters can be sent as a URL encoded string or JSON (using the appropriate Content-Type header).

Parameter	Type	Required	Description
name	string	Required	This is the username of the person you wish to add as a subscriber. In the case of YouTube, it would be the user's YouTube channel URL.

Get subscriber by id

curl -X GET "https://api.nightbot.tv/1/subscribers/56739fb5d0c250946ed67448" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200,
    "subscriber": {
        "_id": "56739fb5d0c250946ed67448",
        "createdAt": "2015-12-18T05:55:01.458Z",
        "updatedAt": "2015-12-18T05:55:01.458Z",
        "provider": "twitch",
        "providerId": "96837452",
        "name": "test_user",
        "displayName": "Test_User"
    }
}

Looks up a subscriber by id

HTTP Request

GET https://api.nightbot.tv/1/subscribers/:id

Scope

subscribers

Delete subscriber by id

curl -X DELETE "https://api.nightbot.tv/1/subscribers/56739fb5d0c250946ed67448" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200
}

Deletes a subscriber by id

HTTP Request

DELETE https://api.nightbot.tv/1/subscribers/:id

Scope

subscribers

Timers

The timers endpoints allow you to view, add, edit, and remove channel timers.

Timer Resource

Fields	Type	Description
`_id`	string	The timer's unique ID
`createdAt`	date	The time the timer was created
`enabled`	boolean	The status of the timer. A value of `true` means the timer is enabled, while `false` means the timer is disabled and will not execute.
`interval`	string	The timer interval in cron syntax. Minimum interval is once per 5 minutes.
`lines`	number	This is the minimum amount of chat lines per 5 minutes required to activate the timer. This is useful in slow chats to prevent Nightbot from spamming in an empty channel.
`message`	string	The message Nightbot sends to chat when the command is called. It can contain variables for extra functionality.
`name`	string	The timer name (has no real significance but gives you a quick reference to what the timer does)
`nextRunAt`	date	The next scheduled time the timer will execute
`updatedAt`	date	The last time the timer was updated

Get timers

curl -X GET "https://api.nightbot.tv/1/timers" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "_total": 1,
    "status": 200,
    "timers": [
        {
            "_id": "568a4d15df4510b03deb65fc",
            "createdAt": "2016-01-04T10:44:37.440Z",
            "updatedAt": "2016-01-04T10:44:37.440Z",
            "name": "test",
            "message": "test",
            "interval": "*/15 * * * *",
            "nextRunAt": "1970-01-01T00:00:00.000Z",
            "lines": 2,
            "enabled": true
        },
        ...
    ]
}

Gets the current API user's timers list

HTTP Request

GET https://api.nightbot.tv/1/timers

Scope

timers

Add new timer

curl -X POST "https://api.nightbot.tv/1/timers" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \
  -d "message=test%20message" \
  -d "interval=*%2F15%20*%20*%20*%20*" \
  -d "lines=5" \
  -d "name=test"

{
    "status": 200,
    "command": {
        "createdAt": "2016-01-04T05:26:27.593Z",
        "updatedAt": "2016-01-04T05:26:27.593Z",
        "name": "test",
        "message": "test message",
        "_id": "568a02834184d1a07660f380",
        "interval": "*/15 * * * *",
        "nextRunAt": "1970-01-01T00:00:00.000Z",
        "lines": 2,
        "enabled": true
    }
}

Adds a new timer to the current user's channel

HTTP Request

POST https://api.nightbot.tv/1/timers

Scope

timers

Body Parameters

The following parameters can be sent as a URL encoded string or JSON (using the appropriate Content-Type header).

Parameter	Type	Required	Description
enabled	boolean	Optional	The status of the timer. A value of `true` means the timer is enabled, while `false` means the timer is disabled and will not execute.
interval	string	Required	The timer interval in cron syntax. Minimum interval is once per 5 minutes.
lines	number	Required	This is the minimum amount of chat lines per 5 minutes required to activate the timer. This is useful in slow chats to prevent Nightbot from spamming in an empty channel.
message	string	Required	The message to send to chat. It can contain variables for extra functionality. Maximum length: 400 characters
name	string	Required	The timer name (has no real significance but gives you a quick reference to what the timer does)

Get timer by id

curl -X GET "https://api.nightbot.tv/1/timers/568a4d15df4510b03deb65fc" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200,
    "timer": {
        "_id": "568a4d15df4510b03deb65fc",
        "createdAt": "2016-01-04T10:44:37.440Z",
        "updatedAt": "2016-01-04T10:44:37.440Z",
        "name": "test",
        "message": "test",
        "interval": "*/15 * * * *",
        "nextRunAt": "1970-01-01T00:00:00.000Z",
        "lines": 2,
        "enabled": true
    }
}

Looks up a timer by id

HTTP Request

GET https://api.nightbot.tv/1/timers/:id

Scope

timers

Edit timer by id

curl -X PUT "https://api.nightbot.tv/1/timers/568a02834184d1a07660f380" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \
  -d "name=testing"

{
    "status": 200,
    "timer": {
        "createdAt": "2016-01-04T05:26:27.593Z",
        "updatedAt": "2016-01-04T05:26:27.593Z",
        "name": "testing",
        "message": "test message",
        "_id": "568a02834184d1a07660f380",
        "interval": "*/15 * * * *",
        "nextRunAt": "1970-01-01T00:00:00.000Z",
        "lines": 2,
        "enabled": true
    }
}

Edits a timer by its id.

HTTP Request

PUT https://api.nightbot.tv/1/timers/:id

Scope

timers

Body Parameters

Parameter	Type	Required	Description
enabled	boolean	Optional	The status of the timer. A value of `true` means the timer is enabled, while `false` means the timer is disabled and will not execute.
interval	string	Optional	The timer interval in cron syntax. Minimum interval is once per 5 minutes.
lines	number	Optional	This is the minimum amount of chat lines per 5 minutes required to activate the timer. This is useful in slow chats to prevent Nightbot from spamming in an empty channel.
message	string	Optional	The message to send to chat. It can contain variables for extra functionality. Maximum length: 400 characters
name	string	Optional	The timer name (has no real significance but gives you a quick reference to what the timer does)

Delete timer by id

curl -X DELETE "https://api.nightbot.tv/1/timers/568a4d15df4510b03deb65fc" \
  -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23"

{
    "status": 200
}

Deletes a timer by id

HTTP Request

DELETE https://api.nightbot.tv/1/timers/:id

Scope

timers