Platform: API

The redball restful API is disabled by default. Enable it by generating an API key on the System Config page.

The API URL is HTTP_ROOT/api/v1, for example http://localhost:8087/api/v1 or http://127.0.0.1:8087/api/v1 depending on your HTTP root.

Every request must include the apikey parameter, with your API key as the value. For example: http://localhost:8087/api/v1/bots?apikey=1234567890abcdefghijklmnopqrstuvwxyz.

Each API response will by in JSON format with the following top-level keys:

• meta - dict containing api_version and timestamp when the response was generated
• errors - string or list of strings if request encountered error(s)
• response - requested data

GET /api/v1/bots

Request with no additional parameters to return a list of bots with their id, name, type, associated reddit authorization id, auto run setting, and current status.

Request with bot id for info about a specific bot: GET /api/v1/bots/1.

Request with bot id and specific configuration field to return only the bot id and requested field: GET /api/v1/bots/1/name.

Request with config as the field name (/api/v1/bots/<bot_id>/config) to return the configuration settings for the bot. The config data will be in the same format you can use with POST and PUT, but it will include id and bot id which you should remove when importing (although they will be ignored).

Request with config as field name followed by a specific botConfig id (/api/v1/bots/<bot_id>/config/<botConfig_id>) to return the single configuration setting.

POST /api/v1/bots

Use POST to create a new record. The request will fail if the bot already exists (use PUT to update).

The following parameters are accepted:

• name (required) - the name you want to assign to your new bot
• botType (required) - the internal id of the type of bot you want to create (obtain through bottypes endpoint)
• autoRun (required) - True or False, if you want the bot to run on startup or not
• redditAuth (optional) - if included, should be the internal id of the reddit authorization obtained through the redditauth endpoint.

If successful, the response will include the new bot id.

Use POST /api/v1/bots/<bot_id>/config to add configuration settings to a given bot. Existing settings will not be updated. Use PUT to overwrite existing settings.

Create a single config setting with the following fields:

• category (required)
• key (required)
• val (required)
• description - will be displayed on the bot settings page; key will be displayed if description is empty
• type - string containing either str, int, bool, or list - currently not used but intended to help with config validation
• options - list of valid values for the key; if present, the field will be a dropdown instead of a text field ont he bot settings page
• subkeys - list of keys (in the same category) which are subkeys of the given key
• parent_key - to be populated on subkeys, the key of the parent

To create multiple settings in a single request, include the settings info in json format in the POST request body using the following structure. The only required fields are category, key, and val.

The only difference between POST /api/v1/bots/<bot_id>/config and PUT /api/v1/bots/<bot_id>/config is POST will preserve existing values and PUT will replace existing values.

Neither POST nor PUT will delete settings that exist in the DB but do not exist in the uploaded file. Either DELETE via API first (DELETE /api/v1/bots/<bot_id>/config to delete all settings), or upload the file with the clean option in the UI.

{
	"<Category1>" : [{
			"key" : "<KEY>",
			"description" : "<DESCRIPTION>",
			"type" : "<str OR int OR bool OR list>",
			"val": "<VALUE>",
			"options" : ["<opt1>", "<opt2>", "<opt3>"],
			"subkeys" : ["<subkey1_key>", "<subkey2_key>", "<subkey3_key>"],
			"parent_key" : "<parent_key>"
		},{
			"key" : "<KEY>",
			"description" : "<DESCRIPTION>",
			"type" : "<str OR int OR bool OR list>",
			"val": "<VALUE>",
			"options" : ["<opt1>", "<opt2>", "<opt3>"],
			"subkeys" : ["<subkey1_key>", "<subkey2_key>", "<subkey3_key>"],
			"parent_key" : "<parent_key>"
		}],
	"<Category2>" : [{
			"key" : "<KEY>",
			"description" : "<DESCRIPTION>",
			"type" : "<str OR int OR bool OR list>",
			"val": "<VALUE>",
			"options" : ["<opt1>", "<opt2>", "<opt3>"],
			"subkeys" : ["<subkey1_key>", "<subkey2_key>", "<subkey3_key>"],
			"parent_key" : "<parent_key>"
		},{
			"key" : "<KEY>",
			"description" : "<DESCRIPTION>",
			"type" : "<str OR int OR bool OR list>",
			"val": "<VALUE>",
			"options" : ["<opt1>", "<opt2>", "<opt3>"],
			"subkeys" : ["<subkey1_key>", "<subkey2_key>", "<subkey3_key>"],
			"parent_key" : "<parent_key>"
		}]
}

PUT /api/v1/bots/<bot_id>

Use PUT to update an existing bot. Bot_id should be the internal id of the bot to update.

Supported parameters include name, botType, autoRun, and redditAuth. Include any or all that you want to update.

Start and stop a bot via PUT /api/v1/bots/<bot_id>/start and PUT /api/v1/bots/<bot_id>/stop.

Update bot configuration with json payload via PUT /api/v1/bots/<bot_id>/config. This functions the same as POST to the same endpoint, except existing values will be overwritten in addition to new settings being inserted.

Update a single bot configuration setting via PUT /api/v1/bots/<bot_id>/config/<botConfig_id>. The same fields are supported as listed under POST to create a single configuration setting.

DELETE /api/v1/bots/<bot_id>

Use DELETE to delete a bot. Bot_id should be the internal id of the bot you want to delete.

Use DELETE /api/v1/bots/<bot_id>/config to delete all config for the given bot id, or DELETE /api/v1/bots/<bot_id>/config/<botConfig_id> to delete a specific configuration setting.

Use extreme caution, because DELETE actions cannot be undone.

GET /api/v1/botTypes

Request with no additional parameters to return a list of bot types with their id, name, description, and module name.

Request with botType id for info about a specific bot type: GET /api/v1/bottypes/1.

Request with botType id and specific configuration field to return only the botType id and requested field: GET /api/v1/bottypes/1/moduleName.

POST /api/v1/botTypes

Use POST to create a new record. The request will fail if the record already exists (use PUT to update).

The following parameters are accepted:

• description (required) - the name of the bot type you want to create
• moduleName (required) - the filename of the python module associated with the new bot type; module should be placed in the /bots directory

PUT /api/v1/botTypes/<botType_id>

Use PUT to update an existing record. BotType_id should be the internal id of the botType to update.

Supported parameters include description and moduleName. Include one or both.

DELETE /api/v1/botTypes/<botType_id>

Use DELETE to delete a record. BotType_id should be the internal id of the botType you want to delete.

Use extreme caution, because this action cannot be undone.

GET /api/v1/redditAuths

Request with no additional parameters to return a list of reddit authorizations with their id, description, reddit_appId, reddit_appSecret, reddit_scopes, reddit_refreshToken, and reddit_uniqueCode.

Request with redditAuth id for info about a specific reddit authorization: GET /api/v1/redditAuths/1.

Request with redditAuth id and specific configuration field to return only the redditAuth id and requested field: GET /api/v1/redditAuths/1/reddit_scopes.

POST /api/v1/redditAuths

Use POST to create a new record. The request will fail if the record already exists (use PUT to update).

The following parameters are accepted:

• description (required) - the name of the reddit authorization you want to create (e.g. BotUserName AllScopes)
• reddit_appId (required) - app id from your reddit app (see Reddit Authorizations section)
• reddit_appSecret (required) - app secret from your reddit app (see Reddit Authorizations section)
• reddit_scopes (required) - reddit scopes to authorize (see scopes listed in Reddit Authorizations section). The format for reddit_scopes should be ['scope1','scope2','scopeN'].
• reddit_refreshToken (optional) - refresh token, which will normally be obtained through redball (see Reddit Authorizations section)

PUT /api/v1/redditAuths/<redditAuth_id>

Use PUT to update an existing record. redditAuth_id should be the internal id of the redditAuth to update.

Supported parameters include description, reddit_appId, reddit_appSecret, reddit_scopes, and reddit_refreshToken. Include any or all that you wish to update.

The format for reddit_scopes should be ['scope1','scope2','scopeN'].

DELETE /api/v1/redditAuths/<redditAuth_id>

Use DELETE to delete a record. RedditAuth_id should be the internal id of the redditAuth you want to delete.

Use extreme caution, because this action cannot be undone.