api-docs.nightbot.tv Open in urlscan Pro
2606:4700:20::681a:c3b  Public Scan

Form analysis
0 forms found in the DOM

Text Content

NAV
cURL

 * Introduction
 * Errors
 * Userlevels
 * OAuth 2
   * Basic Steps
   * Scopes
   * Authorization Code Flow
   * Implicit Flow
   * Refreshing Tokens
   * Revoking Tokens
 * Channel
   * Channel Resource
   * Get channel
   * Join channel
   * Part channel
   * Send channel message
 * Commands
   * Custom Command Resource
   * Default Command Resource
   * Get custom commands
   * Add new custom command
   * Get custom command by id
   * Edit custom command by id
   * Delete custom command by id
   * Get default commands
   * Get default command by name
   * Edit default command by name
 * Me
   * Authorization Resource
   * User Resource
   * Get current user
 * Regulars
   * Regular Resource
   * Get regulars
   * Add new regular
   * Get regular by id
   * Delete regular by id
 * Song Requests
   * Song Request Settings Resource
   * Playlist Item Resource
   * Queue Item Resource
   * Get song request settings
   * Edit song request settings
   * Get playlist
   * Add new playlist item
   * Clear playlist
   * Import remote playlist
   * Get playlist item by id
   * Delete playlist item by id
   * Get queue
   * Add new queue item
   * Clear queue
   * Resume current queue item
   * Pause current queue item
   * Skip current queue item
   * Get queue item by id
   * Delete queue item by id
   * Promote queue item
 * Spam Protection
   * Filter Resource
   * Get filters
   * Get filter by type
   * Edit filter by type
 * Subscribers
   * Subscriber Resource
   * Get subscribers
   * Add new subscriber
   * Get subscriber by id
   * Delete subscriber by id
 * Timers
   * Timer Resource
   * Get timers
   * Add new timer
   * Get timer by id
   * Edit timer by id
   * Delete timer by id

 * Contribute to these docs
 * (Docs Powered by Slate)


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.

Note: Save refresh tokens in secure long-term storage and continue to use them
as long as they remain valid. Limits apply to the number of refresh tokens that
are issued per client-user combination, and per user across all clients, and
these limits are different. If your application requests enough refresh tokens
to go over one of the limits, older refresh tokens stop working.


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.

Be sure to keep your client secret confidential. It should only be kept
server-side, and should not be embedded in client applications.

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

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

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 (`*`). 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

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

cURL