NAV
cURL

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:

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.

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:

Accessing the API via query string:

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:

Accessing the API via query string:

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

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 Optional The minimum amount of seconds between command usage (prevents spam). Defaults to 30
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 Optional The userlevel required to use the command. Defaults to everyone

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

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

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

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

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

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
blacklist string Optional New-line delimited list of blacklisted phrases. Wildcards can be used. 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. 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
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

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