NAV

KBot

shell

Introduction

This documentation is for ksyncbot's API endpoints.

Since the project is constantly growing, expect changes and updates in endpoints, but don't worry, everything is backwards compatible.

Contact

If you have any questions or requests regarding the API or the project in general, create a suggestion in my bot by typing
kb suggest <your_message> in Twitch chat with my bot present, eventually you can email me at dev@kunszg.com

API reference

Statistics

curl -X GET "https://kunszg.com/api/stats"

The above command returns JSON structured like this:

{
    "modules": {
        "remindersLastSeen": 1624137483000,
        "loggerLastSeen": 1624137541000,
        "apiLastSeen": 1624137491000,
        "botLastSeen": 1624137522000
    },
    "bot": {
        "isRestarting": false,
        "codeUptime": 1624037321476,
        "linesOfCode": 10185,
        "usersLogged": 2574066,
        "commandsExecutions": 211188
    },
    "github": {
        "commits": 2707
    },
    "twitch": {
        "totalViewCount": 1500
    },
}

This endpoint retrieves statistics related to ksyncbot and its workspace.

HTTP Request

GET https://kunszg.com/api/stats

Query Parameters

Parameter Default Description
- - -

Channels

curl -X GET "https://kunszg.com/api/channels?details=true&channel=nymn"

The above command returns JSON structured like this:

{
    "code": 200,
    "count": 1,
    "channels": {
        "nymn": {
            "id": 4,
            "userId": 62300805,
            "name": "nymn",
            "liveStatus": "live",
            "isStrict": false,
            "created": "2020-10-19T17:37:44.000Z",
            "createdTimestamp": 1603129064000,
            "commandsUsed": 54033,
            "isBanphraseApiActive": true,
            "banphraseApi": "https://nymn.pajbot.com/api/v1/banphrases/test",
            "logger": {
                "id": 3,
                "isLogging": true,
                "created": "2020-04-05T04:14:04.000Z",
                "createdTimestamp": 1586060044000,
                "tableSize": 3444
            }
        }
    }
}

This endpoint retrieves channels in which ksyncbot is currently operational.

HTTP Request

GET https://kunszg.com/api/channels

URL Parameters

Parameter Default Description
details false Extends the returned data by details about the channels.
channel - retrieves the specified channel, works only when details parameter is set to true.

Response Fields

Parameter Type Description
code integer HTTP response status code, set to 200 on success.
count integer Count of channels returned in the response.
id integer Internal unique identification number of given channel in both standalone bot and logger. At the same time this number defines position at which the channel should be joined whenever the bot is launching (lower id's get to use the bot faster after restart). In object property of logger this field returns null when isLogging parameter is set to false.
userId integer Twitch user id of the channel.
name string Twitch channel name.
liveStatus string States whether the channel is currently "live" or "offline".
isStrict boolean When set to true the bot is going to ignore incomming commands when given channel is "live" and the response message is going to be shortened.
created string UTC date of standalone bot joining the channel. In object property of logger this field returns null when isLogging parameter is set to false.
createdTimestamp integer Timestamp in milliseconds of standalone bot joining the channel. In object property of logger this field returns null when isLogging parameter is set to false.
commandsUsed integer Amount of commands used in the channel.
isBanphraseApiActive boolean States whether the banphrase API is assigned to the channel and is enabled on the bot's end.
banphraseApi string Returns the channel assigned banphrase API (if there is one and it's enabled) as string, and returns null if none was assigned (or enabled).
isLogging boolean If set to true the channel is currently being logged, if set to false logger is not operational in the given channel.
tableSize integer Returns the apparent size of logs file of given channel in MB. This field returns null when isLogging parameter is set to false.

Errors

The ksyncbot API uses or will use in future the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- Requested resource did not match your permissions.
404 Not Found -- Requested resource was not found.
405 Method Not Allowed -- Requested method is not allowed for this resource.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The resource requested has been removed.
429 Too Many Requests -- Sending too many requests.
500 Internal Server Error -- Server is currently not available. Try again later.
503 Service Unavailable -- Temporarily offline for maintenance. Please try again later.
cURL