Introduction

Welcome to the DisComm Bots' API Documentation! You can use our API to access DisComm Bots' (e.g. GiselleBot's) API endpoints, providing alternative ways of setting up your Discord modules.

For any given API endpoint, you can view HTTP request/response examples in the dark area to the right of this page.

Unless specified otherwise, the response that the APIs will send will always be a JSON object. Because of this, it is usually suggested, or mandatory, to add the Content-Type: application/json header to your requests.

Throughout the documentation, <APP_CLIENT_ID> or :appClientId will refer to the ID of the bot you want to interface with. For example, in interacting with GiselleBot, you should replace <APP_CLIENT_ID> or :appClientId with 356831787445387285.

Authorization

HTTP Request Example(s)

GET /<API_ENDPOINT> HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: abcdefghijklmnopqrstuvwxyz0123456789

POST /<API_ENDPOINT> HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Content-Type: application/json
Authorization: abcdefghijklmnopqrstuvwxyz0123456789

{ "key": "value" }

Make sure to replace abcdefghijklmnopqrstuvwxyz0123456789 with your access token.

DisComm Bots' API endpoints are accessed through the use of an API gateway. The API gateway uses your Discord account identifier to match with your Discord user info, show your authorized features and fetch the info you need from the Discord API.

The API gateway expects the received access token to be included in all API requests to the server, in a header that looks like the following:

Authorization: abcdefghijklmnopqrstuvwxyz0123456789

You must replace abcdefghijklmnopqrstuvwxyz0123456789 with your personal access token.

The API gateway also accepts the following header formats:

Authorization: Bearer abcdefghijklmnopqrstuvwxyz0123456789

X-Access-Token: abcdefghijklmnopqrstuvwxyz0123456789

X-Access-Token: Bearer abcdefghijklmnopqrstuvwxyz0123456789

Each request shall also have a User-Agent header to identify your client.

Obtaining an Access Token

In order to obtain an API gateway access token, users first need to authenticate themselves with their Discord account.

The gateway will obtain the user's Discord identity, including the Discord access token. The Discord token will be retained (encrypted) by the API gateway and will be hidden to the front-end, enhancing security for the end-user.

Obtaining the access token to the API gateway is a 2-step process.

Authentication: Step 1

HTTP Request Example

GET /discord/login HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com

HTTP Response Example

HTTP/1.1 307 Temporary Redirect
Location: https://discord.com/api/oauth2/authorize?client_id=<APP_CLIENT_ID>...

First of all, generate a new Discord login request by hitting the following gateway endpoint with your provided callback URL:

HTTP Request

GET https://gateway.cycloptux.com/auth/discord/login?redirect_uri=<CALLBACK_URL>

HTTP Response

Temporary Redirect. Redirecting to https://discord.com/api/oauth2/authorize?client_id=<APP_CLIENT_ID>...

The user will be redirected to the Discord login page. Upon a successful login, the callback URL will contain a new query string parameter, ?code=<TEMPORARY_TOKEN>, that will be needed for the second login phase.

Authentication: Step 2

HTTP Request Example

POST /discord/token HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <TEMPORARY_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": <ACCESS_TOKEN>,
    "token_type": "Bearer",
    "expires_in": <SECONDS_LEFT_UNTIL_EXPIRATION>,
    "refresh_token": <REFRESH_TOKEN>,
    "scope": <TOKEN_SCOPES>,
    "issued_at": <ISSUED_DATE>,
    "expiration_date": <EXPIRATION_DATE>,
    "message": "Authentication successful."
}

The temporary short token must then be exchanged with a full token in order to send further requests to the API gateway:

HTTP Request

POST https://gateway.cycloptux.com/auth/discord/token

Using this header:

Authorization: <TEMPORARY_TOKEN>

HTTP Response

Parameter	Type	Description
access_token	String	The access token you need to authenticate requests. Use this in the `Authorization` header.
token_type	String	The access token type. This will always be "Bearer".
expires_in	Integer	Seconds left until the access token expires.
refresh_token	String	The refresh token you need to obtain a new access token when this expires.
scope	String	Space-separated list of access token scopes. Currently, this will always be "all".
issued_at	String	UTC timestamp of the access token issue date.
expiration_date	String	UTC timestamp of the access token expiration date.
message	String	A human-readable message confirming the authentication was successful.

The long access_token provided here must be added to all requests in order to identify the user and its authorization set. The access_token and refresh_token will only be shown in this response and will not be obtained through subsequent requests. Make sure to save them.

Verifying an Existing Access Token

HTTP Request Example

POST /discord/token/check HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "token_type": "Bearer",
    "expires_in": <SECONDS_LEFT_UNTIL_EXPIRATION>,
    "scope": <TOKEN_SCOPES>,
    "is_valid": true,
    "issued_at": <ISSUED_DATE>,
    "expiration_date": <EXPIRATION_DATE>,
    "message": "Authentication token is valid."
}

Use this endpoint to verify the time left on your token until it must be renewed.

HTTP Request

POST https://gateway.cycloptux.com/auth/discord/token/check

Using this header:

Authorization: <ACCESS_TOKEN>

HTTP Response

Parameter	Type	Description
token_type	String	The access token type. This will always be "Bearer".
expires_in	Integer	Seconds left until the access token expires.
scope	String	Space-separated list of access token scopes. Currently, this will always be "all".
is_valid	Boolean	Whether the provided token is still valid or must be renewed.
issued_at	String	UTC timestamp of the access token issue date.
expiration_date	String	UTC timestamp of the access token expiration date.
message	String	A human-readable message explaining whether the token is still valid or not.

Refreshing an Access Token

HTTP Request Example

POST /discord/token/refresh HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
X-Refresh-Token: <REFRESH_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": <ACCESS_TOKEN>,
    "token_type": "Bearer",
    "expires_in": <SECONDS_LEFT_UNTIL_EXPIRATION>,
    "refresh_token": <REFRESH_TOKEN>,
    "scope": <TOKEN_SCOPES>,
    "issued_at": <ISSUED_DATE>,
    "expiration_date": <EXPIRATION_DATE>,
    "message": "Authentication successful."
}

Use this endpoint to obtain a new access token from a valid refresh token.

HTTP Request

POST https://gateway.cycloptux.com/auth/discord/token/refresh

Using this header:

X-Refresh-Token: <REFRESH_TOKEN>

HTTP Response

Parameter	Type	Description
access_token	String	The access token you need to authenticate requests. Use this in the `Authorization` header.
token_type	String	The access token type. This will always be "Bearer".
expires_in	Integer	Seconds left until the access token expires.
refresh_token	String	The refresh token you need to obtain a new access token when this expires.
scope	String	Space-separated list of access token scopes. Currently, this will always be "all".
issued_at	String	UTC timestamp of the access token issue date.
expiration_date	String	UTC timestamp of the access token expiration date.
message	String	A human-readable message confirming the authentication was successful.

Revoking an Access Token

HTTP Request Example

POST /discord/token/revoke HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}

Use this endpoint to revoke an existing access token and the corresponding refresh token.

HTTP Request

POST https://gateway.cycloptux.com/auth/discord/token/revoke

Using this header:

Authorization: <ACCESS_TOKEN>

HTTP Response

The response consists of an atomic object, containing a success parameter (Boolean) indicating whether the token was successfully revoked.

General Endpoints

These endpoints are used to access the Discord user's and available bots' information.

Get User Info

HTTP Request Example

GET /user HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "username": "cycloptux",
    "discriminator": "1543",
    "id": "220081163660689408",
    "avatar": "f245375afcc268bcf1d388a5cd59fb77",
    "locale": "en-US"
}

This endpoint retrieves basic information about the logged Discord user.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/user

HTTP Response

Parameter	Type	Description
username	String	The Discord user's username.
discriminator	String	The Discord user's discriminator.
id	String	The Discord user's ID.
avatar	String	The Discord user's avatar hash.
locale	String	The Discord user's chosen language option.

Get Available Bots

HTTP Request Example

GET /bots HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "bots": [
        {
            "id": "356831787445387285",
            "name": "GiselleBot",
            "icon": "45ba76c8b8f1671d3afdd86406e1ff36"
        }
    ]
}

This endpoint retrieves the list of available bots for the Discord user. The bots array can have [0..N] cardinality. The id attribute of a bot must be used in place of :appClientId in subsequent requests when interacting with the specific bot.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots

HTTP Response

The response contains the bots array. Each element of the array has the following parameters:

Parameter	Type	Description
id	String	The bot's ID.
name	String	The bot's username.
icon	String	The bot's icon hash.

Get Available Servers

HTTP Request Example

GET /bots/356831787445387285/servers HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "servers": [
        {
            "id": "533372744130363392",
            "name": "GiselleBot Support Center",
            "icon": "96c07853504ab639eae57202115f1654"
        }
    ]
}

This endpoint retrieves the list of available servers for a specific bot. The servers array can have [1..N] cardinality.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers

HTTP Response

The response contains the servers array. Each element of the array has the following parameters:

Parameter	Type	Description
id	String	The server ID.
name	String	The server name.
icon	String	The server icon hash.

Get a Specific Server

HTTP Request Example

GET /bots/356831787445387285/servers/533372744130363392 HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "533372744130363392",
    "name": "GiselleBot Support Center",
    "icon": "96c07853504ab639eae57202115f1654",
    "channels": [
        {
            "type": "GuildNews",
            "id": "534172002550939648",
            "name": "announcements"
        },
        ...
    ],
    "roles": [
        ...
        {
            "id": "533372744130363392",
            "name": "@everyone",
            "color_hex": "#7289da"
        }
    ]
}

This endpoint retrieves the info about a specific server.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId

HTTP Response

The response contains the same parameters shown on the previous endpoint, with the addition of the channels and roles arrays. Each element of those arrays has the following parameters:

Parameter	Type	Description
id	String	The channel or role ID.
name	String	The channel or role name.
type	String	(Only for channels) The channel type (`GuildText`, `GuildNews`, or `GuildVoice`).
color_hex	String	(Only for roles) The role color, as a hexadecimal string.

Get Available Modules

HTTP Request Example

GET /bots/356831787445387285/servers/533372744130363392/modules HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "modules": [
        {
            "name": "forms",
            "full_name": "Forms Builder",
            "short_description": "",
            "available": true,
            "image": "https://d1fn5var44w6sn.cloudfront.net/module_icons/forms.png"
        },
        ...
    ]
}

This endpoint retrieves the list of available modules for the selected server.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules

HTTP Response

The response contains the modules array. Each element of the array has the following parameters:

Parameter	Type	Description
name	String	The technical name of the module (used in API requests).
full_name	String	The human-readable name of the module.
short_description	String	A short description of the module.
available	Boolean	Whether the module is configurable by the user, according to their permissions.
image	String	The module icon URL.

Get the Server Audit Logs

HTTP Request Example

POST /bots/356831787445387285/servers/533372744130363392/logs HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

{ "module": "forms" }

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "logs": [
        {
            "id": "600a0b4dbb0267534f10abed",
            "timestamp": "2021-01-21T23:16:29.033Z",
            "user_id": "220081163660689408",
            "user_name": "cycloptux#1543",
            "user_avatar": "f245375afcc268bcf1d388a5cd59fb77",
            "module_name": "forms",
            "item_identifier": 2,
            "event_type": "PATCH",
            "event_string": "[cycloptux#1543](220081163660689408) updated an item with identifier 2 in the forms module."
        },
        ...
    ],
    "page": 1,
    "page_size": 10,
    "page_max": 6
}

This endpoint retrieves the technical audit logs for the selected server. The access to this endpoint requires the Discord user to have "View Audit Logs" permissions in the corresponding server.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/logs

Audit logs entries fetched through this endpoint are paginated.

Supported query parameters:

Parameter	Type	Required	Description
module	String	false	The technical name of the module (refer to the `/modules` endpoint). If not specified, the output will include the logs of all modules.
start	String/Integer	false	The initial timestamp for the logs being fetched. Supported formats are ISO 8601 strings, or Unix Epoch Time.
end	String/Integer	false	The final timestamp for the logs being fetched. Supported formats are ISO 8601 strings, or Unix Epoch Time.
page_size	Integer	false	The number of entries to fetch in a single request (Default: 10, Maximum: 100).
page	Integer	false	The page to request (Default: 1).

HTTP Response

The response contains the logs array. Each element of the array has the following parameters:

Parameter	Type	Description
id	String	The unique ID of the log entry.
timestamp	String	The timestamp of the executed action.
user_id	String	The ID of the Discord user that executed the action.
user_name	String	The username of the Discord user that executed the action.
user_avatar	String	The avatar hash of the Discord user that executed the action.
module_name	String	The technical name of the module.
item_identifier	Integer	The identifier of the item being accessed or modified (if applicable).
event_type	String	The type of the action that was performed. Possible values of this parameter are `GET` (item read/accessed), `PUSH` (item created/added), `PATCH` (item updated), `DELETE` (item cancelled/removed).
event_string	String	A human-readable description of the action that was performed.

Additionally, the following pagination-related parameters are passed in the response:

Parameter	Type	Description
page	Integer	The current page being shown, for the specific query.
page_size	Integer	The requested page size.
page_max	Integer	The maximum page that can be requested, for the specific query.

Forms Builder

These endpoints control the Forms Builder module.

Get Trello Options

HTTP Request Example

GET /trelloOptions HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "options": [
        "Description",
        "Title",
        "List",
        "Label",
        "Attachment",
        "Private"
    ]
}

This endpoint retrieves the list of available options that can be used, when generating a form question, to map the question fields to Trello board/card options.

The same information is provided through the Get Form endpoint.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/forms/trelloOptions

HTTP Response

The response contains the options array of strings, with the following values:

Value	Description
Description	The description (content) of a Trello card.
Title	The title of a Trello card.
List	The name of a list on the Trello board.
Label	A label on a Trello board, assigned to the card.
Attachment	The attachment of a Trello card.
Private	Any field marked with "Private" will not be sent to Trello.

Get Trello Boards

HTTP Request Example

GET /trelloBoards HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "trello_boards": [
        {
            "id": "0",
            "name": "Disable Trello integration"
        },
        {
            "id": "5c4e576b0386d8313e9e3722",
            "name": "GiselleBot Support Center :: Bug Reports & Future Development"
        }
    ]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "trello_boards": [
        {
            "id": "-1",
            "name": "Trello team not paired"
        }
    ]
}

This endpoint retrieves the list of available Trello boards that can be used, when creating a form question, to publish approved submissions (provided the server has a paired Trello team).

The same information is provided through the Get Form endpoint.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/forms/trelloBoards

HTTP Response

The response contains the trello_boards array. Each element of the array has the following parameters:

Parameter	Type	Description
id	String	The ID of the Trello board.
name	String	The name of the Trello board.

When fetching boards, two "special" boards can be found:

{ "id": "0", "name": "Disable Trello integration" } → This board ID can be passed in certain options in order to disable the Trello integration.
{ "id": "-1", "name": "Trello team not paired" } → This board is shown when the server is not paired to any Trello team.

Get Forms

HTTP Request Example

GET / HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "forms": [
        {
            "workflow_id": 1,
            "trello_integration": true,
            "workflow_live": true,
            "title": "Bug Reports",
            "color_hex": "#3a7fdb"
        },
        ...
    ]
}

This endpoint retrieves the list of all forms in a server.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/forms

HTTP Response

The response contains the forms array. Each element of the array has the following parameters:

Parameter	Type	Description
workflow_id	Integer	The ID of the form.
trello_integration	Boolean	Whether the Trello integration is enabled for the form (a.k.a. "Trello Mode").
workflow_live	Boolean	Whether the form is currently enabled.
title	String	The title of the form.
color_hex	String	The form color, as a hexadecimal string.

Get Form

HTTP Request Example

GET /1 HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "workflow_id": 1,
    "channel_id": "534754593490337802",
    "fwd_channel_ids": [
        "539252303400796211"
    ],
    "role_mentions": [
        "539276949307260928"
    ],
    "timestamp_created": "2019-01-28T01:07:25.274Z",
    "workflow_live": true,
    "trello_integration": true,
    "anonymize": true,
    "disable_downvote": false,
    "disable_upvote": false,
    "extended_embed": true,
    "trello_board": "5c4e576b0386d8313e9e3722",
    "title": "Bug Reports",
    "color_hex": "#3a7fdb",
    "highlight_attachments": false,
    "anonymize_rejection": false,
    "disable_mentions": false,
    "disable_priorities": false,
    "steps": [
        {
            "step_id": 1,
            "type": "reaction",
            "string": "What bot are you leaving a bug report for?",
            "answers_validation": [
                "GiselleBot",
                "Belfast-chan",
                "Other"
            ],
            "char_limit": [
                1,
                2000
            ],
            "alias": "Bot Name",
            "trello_mapping": "Label"
        },
        ...
    ],
    "trello_options": [...],
    "trello_boards": [...]
}

This endpoint retrieves one form for a server.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/forms/:formId

HTTP Response

The response consists of a form object, with following parameters:

Parameter	Type	Description
workflow_id	Integer	The ID of the form.
channel_id	String	The channel ID of the authorization channel.
fwd_channel_ids	Array<String>	The channel IDs of the forwarding channels.
role_mentions	Array<String>	The role IDs of the authorized role(s).
public_mentions	Array<String>	The role IDs of the public role mentions.
timestamp_created	String	The timestamp of the form creation.
workflow_live	Boolean	Whether the form is currently enabled.
trello_integration	Boolean	Whether the Trello integration is enabled for the form (a.k.a. "Trello Mode").
anonymize	Boolean	Whether the public submissionms are anonymized in Discord Mode (hidden submitter info).
disable_downvote	Boolean	Whether the downvote tracking feature (and downvote arrow application for new submissions) is disabled.
disable_upvote	Boolean	Whether the upvote tracking feature (and upvote arrow application for new submissions) is disabled.
extended_embed	Boolean	Whether the extended embed mode is enabled in "Trello Mode" for public in-Discord summary messages.
trello_board	String	The ID of the Trello board linked to the form.
title	String	The title of the form.
color_hex	String	The form color, as a hexadecimal string.
highlight_attachments	Boolean	Whether the attachment highlighting feature is enabled.
anonymize_rejection	Boolean	Whether the name of the user that rejected a submission will appear in the rejection message.
disable_mentions	Boolean	Whether the authorized role(s) will not be mentioned when a new submission is received.
disable_priorities	Boolean	Whether the priority buttons are not applied to the validation message.
steps	Array<Object>	An array of steps (questions) for the form (see below for more info).
trello_options	Array<String>	Equivalent to the `options` array from Get Trello Options.
trello_boards	Array<Object>	Equivalent to the `trello_boards` array from Get Trello Boards.

Each step (question) has the following parameters:

Parameter	Type	Description
step_id	Integer	The ID of the step. This will be recalculated based on the order of the steps when editing the form.
type	String	The type of question. Accepted values are `message` or `reaction`.
string	String	The content of the question.
answers_validation	Array<String>	If `type` is set to `reaction`, the list of possible answers. If `type` is set to `message`, the list of validation words/sentences (answers will be ignored unless the message contains at least one of the chosen words/sentences).
char_limit	Array<Integer>	An array of two elements, specifying the minimum and maximum number of characters an answer can have. The first element must be higher than 0. The second element must be lower than, or equal to, 2000. The second integer must be higher than, or equal to, the first.
alias	String	A short alias/title that will replace the full question when the submission is sent.
trello_mapping	String	The mapping of the question into one of the entities of the Trello board, if "Trello Mode" is enabled. Refer to Get Trello Options.

Create Form

HTTP Request Example

POST / HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

{
    "channel_id": "534754593490337802",
    "fwd_channel_ids": [
        "895420834318020628"
    ],
    "role_mentions": [
        "530800536627314698"
    ],
    "public_mentions": [],
    "trello_integration": false,
    ...
    "steps": [...]
}

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "workflow_id": 4,
    "channel_id": "534754593490337802",
    "fwd_channel_ids": [
        "895420834318020628"
    ],
    "role_mentions": [
        "530800536627314698"
    ],
    "public_mentions": [],
    "trello_integration": false,
    ...
    "steps": [...],
    "trello_options": [...],
    "trello_boards": [...]
}

This endpoint creates a new form for a server.

HTTP Request

POST https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/forms

The request body must include the full form. Validation checks on individual fields are run server-side. Refer to Get Form for the full list of parameters.

HTTP Response

The response consists of a form object. The workflow_id found in the object must be used as formId in subsequent calls.

Refer to Get Form for the full list of parameters.

Update Form

HTTP Request Example

PATCH /1 HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

{
    "workflow_id": 1,
    "channel_id": "534754593490337802",
    ...
    "workflow_live": false,
    ...
    "disable_downvote": true,
    "disable_upvote": true,
    ...
    "steps": [...]
}

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "workflow_id": 1,
    "channel_id": "534754593490337802",
    ...
    "workflow_live": false,
    ...
    "disable_downvote": true,
    "disable_upvote": true,
    ...
    "steps": [...],
    "trello_options": [...],
    "trello_boards": [...]
}

This endpoint updates one form for a server.

HTTP Request

PATCH https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/forms/:formId

The request body must include the full updated form. Validation checks on individual fields are run server-side. Refer to Get Form for the full list of parameters.

HTTP Response

The response consists of a form object.

Refer to Get Form for the full list of parameters.

Delete Form

HTTP Request Example

DELETE /1 HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}

This endpoint deletes one form for a server.

HTTP Request

DELETE https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/forms/:formId

HTTP Response

The response consists of an atomic object, containing a success parameter (Boolean) indicating whether the form was successfully deleted.

Get New Form Template

HTTP Request Example

GET /new HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "workflow_id": null,
    "channel_id": null,
    "fwd_channel_ids": [],
    "role_mentions": [],
    "public_mentions": [],
    "timestamp_created": null,
    "trello_integration": false,
    "trello_board": "-1",
    "workflow_live": false,
    "title": "TITLE_NOT_FOUND",
    "color_hex": "#00d084",
    ...
    "steps": [],
    "trello_options": [...],
    "trello_boards": [...]
}

This endpoint generates a new form template that can be used as a base to create a new form through Create Form.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/forms/new

HTTP Response

The response consists of a "template" form object. The workflow_id is assigned by the server when the template is sent through Create Form.

Refer to Get Form for the full list of parameters.

Instagram Connector

These endpoints control the Instagram Connector module.

Get Instagram User ID

HTTP Request Example

GET /getUserId/discord HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "userId": "1965841892",
    "userName": "discord",
    "displayName": "Discord"
}

This endpoint retrieves the ID of a Instagram user, given their username (i.e. the "@" name).

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/instagram/getUserId/:userName

HTTP Response

The response object contains the following parameters:

Parameter	Type	Description
userId	String	The ID of the Instagram user.
userName	String	The username of the Instagram user (i.e. the "@" name).
displayName	String	The full name of the Instagram user.

Get Instagram Feeds

HTTP Request Example

GET /feeds HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "feeds": [
        {
            "id": "5ffd4fdcac5e41cb40bb8a46",
            "feed_identifier": "23947096",
            "webhook_options": {
                "filter_mode": "OR",
                "filter_event": null,
                "filter_words": null,
                "filter_excl": false,
                "nsfw": null,
                "custom_header": null,
                "webhook-name": null,
                "no-username-overwrite": false,
                "no-avatar-overwrite": false
            },
            "display_info": {
                "user_name": "natgeotravel",
                "display_name": "National Geographic Travel",
                "user_url": "https://www.instagram.com/natgeotravel/"
            },
            "webhook_info": {
                "name": "Instagram",
                "avatar": null,
                "channel_id": "598611422049599524"
            }
        },
        ...
    ]
}

This endpoint retrieves the list of feeds for a server.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/instagram/feeds

HTTP Response

The response contains the feeds array. Each element of the array has the following parameters:

Parameter	Type	Description
id	String	The feed unique ID.
feed_identifier	String	The feed-specific identifier.
webhook_options	Object	The feed-specific webhook options.
webhook_info	Object	The information about the webhook the feed is streaming to.

The webhook_options object contains the following parameters:

Parameter	Type	Description
filter_event	?Array<String>	An array of event types to filter (i.e. whitelist) when posting items to the feed. `null` means that the filter is disabled. When populated, this array can only contain one of these values: `post`.
filter_mode	String	The filter behavior when more than one word is added to the whitelist filter (`filter_words`). This can be either `AND` or `OR`.
nsfw	?String	The NSFW behavior to apply when posting items to the feed if they are deemed to be so. `null` means that the NSFW behavior is disabled. When populated, this can be either `censor`, `skip` or `only`.
filter_words	?Array<String>	An array of words to filter (i.e. whitelist or blacklist, depending on `filter_excl`) when posting items to the feed. `null` means that the filter is disabled.
filter_excl	Boolean	When set to `true`, items will be posted to the feed only if they do not contain the filtered word(s). When set to `false`, items will be posted to the feed only if they do contain the filtered word(s).
custom_header	?String	A custom template to use as message content when posting items to the feed. Custom headers can have a maximum of 1024 characters. `null` means that the default header will be used.
webhook-name	?String	A custom name to use as webhook name (i.e. author) when posting items to the feed. Custom names can have a maximum of 32 characters. `null` means that the default webhook name will be used.
no-username-overwrite	Boolean	When set to `true`, the webhook name defined within the "Integrations" section of Discord will not be overwritten by the default or custom webhook name.
no-avatar-overwrite	Boolean	When set to `true`, the webhook avatar defined within the "Integrations" section of Discord will not be overwritten by the default webhook avatar.

The display_info object contains the following parameters:

Parameter	Type	Description
user_name	String	The username of the Instagram user (i.e. the "@" name).
display_name	String	The full name of the Instagram user.
user_url	String	The profile URL of the Instagram user.

The webhook_info object contains the following parameters:

Parameter	Type	Description
name	String	The name of the webhook.
avatar	String	The avatar hash of the webhook.
channel_id	String	The ID of the channel the webhook belongs to.

Create Instagram Feed

HTTP Request Example

POST /feeds HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

{
    "feed_identifier": "discord",
    "webhook_channel": "598433171641729024",
    "webhook_options": {
        "no-avatar-overwrite": true
    }
}

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "625494b494036b506e6d08ca",
    "feed_identifier": "1965841892",
    "webhook_options": {
        "filter_event": null,
        "filter_words": null,
        "filter_mode": "OR",
        "filter_excl": false,
        "nsfw": null,
        "custom_header": null,
        "webhook-name": null,
        "no-username-overwrite": false,
        "no-avatar-overwrite": true
    },
    "display_info": {
        "user_name": "discord",
        "display_name": "Discord",
        "user_url": "https://www.instagram.com/discord/"
    },
    "webhook_info": {
        "name": "GiselleBot Social Feeds",
        "avatar": null,
        "channel_id": "598433171641729024"
    }
}

This endpoint creates a new feed in a server.

HTTP Request

POST https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/instagram/feeds

Request body parameters:

Parameter	Type	Required	Description
feed_identifier	String	true	The feed-specific identifier.
webhook_channel	String	true*	The ID of the channel the feed will be posted to. If the channel ID is specified, the bot will attempt to create a webhook in that channel (if a usable one isn't already present). At least one between `webhook_channel` and `webhook_url` must be filled.
webhook_url	String	true*	The URL of the webhook the feed will be posted to. At least one between `webhook_channel` and `webhook_url` must be filled.
webhook_options	Object	false	The options for the feed, as described in the corresponding object in Get Instagram Feeds. If you don't pass one or more options, or don't pass the whole object, default options will be used.

feed_identifier must be a Instagram username or user ID. The corresponding parameter of the response will always be the Instagram user ID.

HTTP Response

The response consists of a feed object.

Refer to Get Instagram Feeds for the full list of parameters.

Update Instagram Feed

HTTP Request Example

PATCH /feeds/625494b494036b506e6d08ca HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

{
    "webhook_options": {
        "no-avatar-overwrite": false
    }
}

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "625494b494036b506e6d08ca",
    "feed_identifier": "1965841892",
    "webhook_options": {
        "filter_event": null,
        "filter_words": null,
        "filter_mode": "OR",
        "filter_excl": false,
        "nsfw": null,
        "custom_header": null,
        "webhook-name": null,
        "no-username-overwrite": false,
        "no-avatar-overwrite": false
    },
    "display_info": {
        "user_name": "discord",
        "display_name": "Discord",
        "user_url": "https://www.instagram.com/discord/"
    },
    "webhook_info": {
        "name": "GiselleBot-DEV Social Feeds",
        "avatar": null,
        "channel_id": "598433171641729024"
    }
}

This endpoint updates a feed in a server.

HTTP Request

PATCH https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/instagram/feeds/:feedId

You must send a body with the updated webhook_options object. Refer to Get Instagram Feeds for the full list of parameters. You cannot update the feed_identifier, webhook_channel or webhook_url for an existing feed.

HTTP Response

The response consists of a feed object.

Refer to Get Instagram Feeds for the full list of parameters.

Delete Instagram Feed

HTTP Request Example

DELETE /feeds/625494b494036b506e6d08ca HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}

This endpoint deletes a feed in a server.

HTTP Request

DELETE https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/instagram/feeds/:feedId

HTTP Response

The response consists of an atomic object, containing a success parameter (Boolean) indicating whether the feed was successfully deleted.

Reddit Connector

These endpoints control the Reddit Connector module.

Get Reddit Feeds

HTTP Request Example

GET /feeds HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "feeds": [
        {
            "id": "5ffecffcdd4f55cb3def6e09",
            "feed_identifier": "discordapp",
            "webhook_options": {
                "filter_flair": [
                    "official post"
                ],
                "filter_mode": "OR",
                "filter_words": null,
                "filter_excl": false,
                "nsfw": null,
                "custom_header": null,
                "webhook-name": null,
                "no-username-overwrite": false,
                "no-avatar-overwrite": false
            },
            "webhook_info": {
                "name": "Reddit",
                "avatar": null,
                "channel_id": "697506961540907059"
            }
        },
        ...
    ]
}

This endpoint retrieves the list of feeds for a server.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/reddit/feeds

HTTP Response

The response contains the feeds array. Each element of the array has the following parameters:

Parameter	Type	Description
id	String	The feed unique ID.
feed_identifier	String	The feed-specific identifier.
webhook_options	Object	The feed-specific webhook options.
webhook_info	Object	The information about the webhook the feed is streaming to.

The webhook_options object contains the following parameters:

Parameter	Type	Description
filter_flair	?Array<String>	An array of Reddit flairs to filter (i.e. whitelist) when posting items to the feed. `null` means that the filter is disabled.
filter_mode	String	The filter behavior when more than one word is added to the whitelist filter (`filter_words`). This can be either `AND` or `OR`.
nsfw	?String	The NSFW behavior to apply when posting items to the feed if they are marked as NSFW on Reddit. `null` means that the NSFW behavior is disabled. When populated, this can be either `censor`, `skip` or `only`.
filter_words	?Array<String>	An array of words to filter (i.e. whitelist or blacklist, depending on `filter_excl`) when posting items to the feed. `null` means that the filter is disabled.
filter_excl	Boolean	When set to `true`, items will be posted to the feed only if they do not contain the filtered word(s). When set to `false`, items will be posted to the feed only if they do contain the filtered word(s).
custom_header	?String	A custom template to use as message content when posting items to the feed. Custom headers can have a maximum of 1024 characters. `null` means that the default header will be used.
webhook-name	?String	A custom name to use as webhook name (i.e. author) when posting items to the feed. Custom names can have a maximum of 32 characters. `null` means that the default webhook name will be used.
no-username-overwrite	Boolean	When set to `true`, the webhook name defined within the "Integrations" section of Discord will not be overwritten by the default or custom webhook name.
no-avatar-overwrite	Boolean	When set to `true`, the webhook avatar defined within the "Integrations" section of Discord will not be overwritten by the default webhook avatar.

The webhook_info object contains the following parameters:

Parameter	Type	Description
name	String	The name of the webhook.
avatar	String	The avatar hash of the webhook.
channel_id	String	The ID of the channel the webhook belongs to.

Create Reddit Feed

HTTP Request Example

POST /feeds HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

{
    "feed_identifier": "movies",
    "webhook_channel": "697506961540907059",
    "webhook_options": {
        "filter_flair": ["ama"]
    }
}

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "625206abd39ad73f8a4c369f",
    "feed_identifier": "movies",
    "webhook_options": {
        "filter_flair": [
            "ama"
        ],
        "filter_words": null,
        "filter_mode": "OR",
        "filter_excl": false,
        "nsfw": null,
        "custom_header": null,
        "webhook-name": null,
        "no-username-overwrite": false,
        "no-avatar-overwrite": false
    },
    "webhook_info": {
        "name": "GiselleBot Social Feeds",
        "avatar": null,
        "channel_id": "697506961540907059"
    }
}

This endpoint creates a new feed in a server.

HTTP Request

POST https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/reddit/feeds

Request body parameters:

Parameter	Type	Required	Description
feed_identifier	String	true	The feed-specific identifier.
webhook_channel	String	true*	The ID of the channel the feed will be posted to. If the channel ID is specified, the bot will attempt to create a webhook in that channel (if a usable one isn't already present). At least one between `webhook_channel` and `webhook_url` must be filled.
webhook_url	String	true*	The URL of the webhook the feed will be posted to. At least one between `webhook_channel` and `webhook_url` must be filled.
webhook_options	Object	false	The options for the feed, as described in the corresponding object in Get Reddit Feeds. If you don't pass one or more options, or don't pass the whole object, default options will be used.

HTTP Response

The response consists of a feed object.

Refer to Get Reddit Feeds for the full list of parameters.

Update Reddit Feed

HTTP Request Example

PATCH /feeds/625206abd39ad73f8a4c369f HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

{
    "webhook_options": {
        "filter_flair": ["ama", "news"]
    }
}

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "625206abd39ad73f8a4c369f",
    "feed_identifier": "movies",
    "webhook_options": {
        "filter_flair": [
            "ama",
            "news"
        ],
        "filter_words": null,
        "filter_mode": "OR",
        "filter_excl": false,
        "nsfw": null,
        "custom_header": null,
        "webhook-name": null,
        "no-username-overwrite": false,
        "no-avatar-overwrite": false
    },
    "webhook_info": {
        "name": "GiselleBot Social Feeds",
        "avatar": null,
        "channel_id": "697506961540907059"
    }
}

This endpoint updates a feed in a server.

HTTP Request

PATCH https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/reddit/feeds/:feedId

You must send a body with the updated webhook_options object. Refer to Get Reddit Feeds for the full list of parameters. You cannot update the feed_identifier, webhook_channel or webhook_url for an existing feed.

HTTP Response

The response consists of a feed object.

Refer to Get Reddit Feeds for the full list of parameters.

Delete Reddit Feed

HTTP Request Example

DELETE /feeds/625206abd39ad73f8a4c369f HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}

This endpoint deletes a feed in a server.

HTTP Request

DELETE https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/reddit/feeds/:feedId

HTTP Response

The response consists of an atomic object, containing a success parameter (Boolean) indicating whether the feed was successfully deleted.

RSS Reader

These endpoints control the RSS Reader module.

Get RSS Feeds

HTTP Request Example

GET /feeds HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "feeds": [
        {
            "id": "618177f026e2bba6c5ef7fe0",
            "feed_identifier": "https://discordstatus.com/history.rss",
            "webhook_options": {
                "filter_mode": "OR",
                "custom_header": "**⚠️ New Discord Incident ⚠️**\n\n**Incident**: %title%\n**Description**: %content%\n**Link**: <%url%> ",
                "no-username-overwrite": true,
                "no-avatar-overwrite": true,
                "filter_words": null,
                "filter_excl": false,
                "nsfw": null,
                "webhook-name": null
            },
            "webhook_info": {
                "name": "Discord Status - RSS",
                "avatar": null,
                "channel_id": "697506961540907059"
            }
        },
        ...
    ]
}

This endpoint retrieves the list of feeds for a server.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/rss/feeds

HTTP Response

The response contains the feeds array. Each element of the array has the following parameters:

Parameter	Type	Description
id	String	The feed unique ID.
feed_identifier	String	The feed-specific identifier.
webhook_options	Object	The feed-specific webhook options.
webhook_info	Object	The information about the webhook the feed is streaming to.

The webhook_options object contains the following parameters:

Parameter	Type	Description
filter_mode	String	The filter behavior when more than one word is added to the whitelist filter (`filter_words`). This can be either `AND` or `OR`.
nsfw	?String	The NSFW behavior to apply when posting items to the feed if they are deemed to be so. `null` means that the NSFW behavior is disabled. When populated, this can be either `censor`, `skip` or `only`.
filter_words	?Array<String>	An array of words to filter (i.e. whitelist or blacklist, depending on `filter_excl`) when posting items to the feed. `null` means that the filter is disabled.
filter_excl	Boolean	When set to `true`, items will be posted to the feed only if they do not contain the filtered word(s). When set to `false`, items will be posted to the feed only if they do contain the filtered word(s).
custom_header	?String	A custom template to use as message content when posting items to the feed. Custom headers can have a maximum of 1024 characters. `null` means that the default header will be used.
webhook-name	?String	A custom name to use as webhook name (i.e. author) when posting items to the feed. Custom names can have a maximum of 32 characters. `null` means that the default webhook name will be used.
no-username-overwrite	Boolean	When set to `true`, the webhook name defined within the "Integrations" section of Discord will not be overwritten by the default or custom webhook name.
no-avatar-overwrite	Boolean	When set to `true`, the webhook avatar defined within the "Integrations" section of Discord will not be overwritten by the default webhook avatar.

The webhook_info object contains the following parameters:

Parameter	Type	Description
name	String	The name of the webhook.
avatar	String	The avatar hash of the webhook.
channel_id	String	The ID of the channel the webhook belongs to.

Create RSS Feed

HTTP Request Example

POST /feeds HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

{
    "feed_identifier": "https://www.nytimes.com/svc/collections/v1/publish/https://www.nytimes.com/section/world/rss.xml",
    "webhook_channel": "697506961540907059",
    "webhook_options": {
        "no-username-overwrite": true
    }
}

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "62520ef0d39ad73f8a4c36f1",
    "feed_identifier": "https://www.nytimes.com/svc/collections/v1/publish/https://www.nytimes.com/section/world/rss.xml",
    "webhook_options": {
        "filter_words": null,
        "filter_mode": "OR",
        "filter_excl": false,
        "nsfw": null,
        "custom_header": null,
        "webhook-name": null,
        "no-username-overwrite": true,
        "no-avatar-overwrite": false
    },
    "webhook_info": {
        "name": "GiselleBot Social Feeds",
        "avatar": null,
        "channel_id": "697506961540907059"
    }
}

This endpoint creates a new feed in a server.

HTTP Request

POST https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/rss/feeds

Request body parameters:

Parameter	Type	Required	Description
feed_identifier	String	true	The feed-specific identifier.
webhook_channel	String	true*	The ID of the channel the feed will be posted to. If the channel ID is specified, the bot will attempt to create a webhook in that channel (if a usable one isn't already present). At least one between `webhook_channel` and `webhook_url` must be filled.
webhook_url	String	true*	The URL of the webhook the feed will be posted to. At least one between `webhook_channel` and `webhook_url` must be filled.
webhook_options	Object	false	The options for the feed, as described in the corresponding object in Get RSS Feeds. If you don't pass one or more options, or don't pass the whole object, default options will be used.

HTTP Response

The response consists of a feed object.

Refer to Get RSS Feeds for the full list of parameters.

Update RSS Feed

HTTP Request Example

PATCH /feeds/62520ef0d39ad73f8a4c36f1 HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

{
    "webhook_options": {
        "filter_words": ["war"]
    }
}

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "62520ef0d39ad73f8a4c36f1",
    "feed_identifier": "https://www.nytimes.com/svc/collections/v1/publish/https://www.nytimes.com/section/world/rss.xml",
    "webhook_options": {
        "filter_words": [
            "war"
        ],
        "filter_mode": "OR",
        "filter_excl": false,
        "nsfw": null,
        "custom_header": null,
        "webhook-name": null,
        "no-username-overwrite": false,
        "no-avatar-overwrite": false
    },
    "webhook_info": {
        "name": "GiselleBot Social Feeds",
        "avatar": null,
        "channel_id": "697506961540907059"
    }
}

This endpoint updates a feed in a server.

HTTP Request

PATCH https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/rss/feeds/:feedId

You must send a body with the updated webhook_options object. Refer to Get RSS Feeds for the full list of parameters. You cannot update the feed_identifier, webhook_channel or webhook_url for an existing feed.

HTTP Response

The response consists of a feed object.

Refer to Get RSS Feeds for the full list of parameters.

Delete RSS Feed

HTTP Request Example

DELETE /feeds/62520ef0d39ad73f8a4c36f1 HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}

This endpoint deletes a feed in a server.

HTTP Request

DELETE https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/rss/feeds/:feedId

HTTP Response

The response consists of an atomic object, containing a success parameter (Boolean) indicating whether the feed was successfully deleted.

Twitch Connector

These endpoints control the Twitch Connector module.

Get Twitch User ID

HTTP Request Example

GET /getUserId/discord HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "userId": "92473777",
    "userName": "discord",
    "displayName": "Discord"
}

This endpoint retrieves the ID of a Twitch user, given their username.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/twitch/getUserId/:userName

HTTP Response

The response object contains the following parameters:

Parameter	Type	Description
userId	String	The ID of the Twitch user.
userName	String	The username of the Twitch user.
displayName	String	The display name of the Twitch user (i.e. the channel name).

Get Twitch Game ID

HTTP Request Example

GET /getGameId/just%20chatting HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "gameId": "509658",
    "gameName": "Just Chatting"
}

This endpoint retrieves the ID of a Twitch game, given its name.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/twitch/getGameId/:gameName

HTTP Response

The response consists of an atomic object, containing a gameId parameter (String) indicating the ID of the Twitch game.

The response object contains the following parameters:

Parameter	Type	Description
gameId	String	The ID of the Twitch game.
gameName	String	The name of the Twitch game.

Get Twitch Feeds

HTTP Request Example

GET /feeds HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "feeds": [
        {
            "id": "5fdcabfd7ed3c0c821b66c70",
            "feed_identifier": "427478243",
            "webhook_options": {
                "filter_game": null,
                "filter_event": null,
                "custom_header": null,
                "webhook-name": null,
                "no-username-overwrite": false,
                "no-avatar-overwrite": false
            },
            "display_info": {
                "user_name": "spavald_92",
                "display_name": "spavald_92",
                "user_url": "https://www.twitch.tv/spavald_92",
                "game_names": null
            },
            "webhook_info": {
                "name": "Personal Feeds (Twitch)",
                "avatar": null,
                "channel_id": "789481328328048660"
            }
        },
        ...
    ]
}

This endpoint retrieves the list of feeds for a server.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/twitch/feeds

HTTP Response

The response contains the feeds array. Each element of the array has the following parameters:

Parameter	Type	Description
id	String	The feed unique ID.
feed_identifier	String	The feed-specific identifier.
webhook_options	Object	The feed-specific webhook options.
display_info	Object	The display information about the Twitch user the feed refers to.
webhook_info	Object	The information about the webhook the feed is streaming to.

The webhook_options object contains the following parameters:

Parameter	Type	Description
filter_game	?Array<String>	An array of Twitch game IDs to filter (i.e. whitelist) when posting items to the feed. Refer to `display_info.game_names` for the human-readable names. `null` means that the filter is disabled.
filter_event	?Array<String>	An array of event types to filter (i.e. whitelist) when posting items to the feed. `null` means that the filter is disabled. When populated, this array can only contain one of these values: `live`, `offline`.
custom_header	?String	A custom template to use as message content when posting items to the feed. Custom headers can have a maximum of 1024 characters. `null` means that the default header will be used.
webhook-name	?String	A custom name to use as webhook name (i.e. author) when posting items to the feed. Custom names can have a maximum of 32 characters. `null` means that the default webhook name will be used.
no-username-overwrite	Boolean	When set to `true`, the webhook name defined within the "Integrations" section of Discord will not be overwritten by the default or custom webhook name.
no-avatar-overwrite	Boolean	When set to `true`, the webhook avatar defined within the "Integrations" section of Discord will not be overwritten by the default webhook avatar.

The display_info object contains the following parameters:

Parameter	Type	Description
user_name	String	The username of the Twitch user.
display_name	String	The display name of the Twitch user (i.e. the channel name).
user_url	String	The profile URL of the Twitch user.
game_names	?Array<String>	If `filter_game` is set, this array will contain the human-readable game names corresponding to the `filter_game` IDs.

The webhook_info object contains the following parameters:

Parameter	Type	Description
name	String	The name of the webhook.
avatar	String	The avatar hash of the webhook.
channel_id	String	The ID of the channel the webhook belongs to.

Create Twitch Feed

HTTP Request Example

POST /feeds HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

{
    "feed_identifier": "92473777",
    "webhook_channel": "789481328328048660",
    "webhook_options": {
        "filter_event": ["live"]
    }
}

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "62535fdab94a1c7f5e1d19f4",
    "feed_identifier": "92473777",
    "webhook_options": {
        "filter_game": null,
        "filter_event": [
            "live"
        ],
        "custom_header": null,
        "webhook-name": null,
        "no-username-overwrite": false,
        "no-avatar-overwrite": false
    },
    "display_info": {
        "user_name": "discord",
        "display_name": "Discord",
        "user_url": "https://www.twitch.tv/discord",
        "game_names": null
    },
    "webhook_info": {
        "name": "GiselleBot Social Feeds",
        "avatar": null,
        "channel_id": "789481328328048660"
    }
}

This endpoint creates a new feed in a server.

HTTP Request

POST https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/twitch/feeds

Request body parameters:

Parameter	Type	Required	Description
feed_identifier	String	true	The feed-specific identifier.
webhook_channel	String	true*	The ID of the channel the feed will be posted to. If the channel ID is specified, the bot will attempt to create a webhook in that channel (if a usable one isn't already present). At least one between `webhook_channel` and `webhook_url` must be filled.
webhook_url	String	true*	The URL of the webhook the feed will be posted to. At least one between `webhook_channel` and `webhook_url` must be filled.
webhook_options	Object	false	The options for the feed, as described in the corresponding object in Get Twitch Feeds. If you don't pass one or more options, or don't pass the whole object, default options will be used.

feed_identifier must be a Twitch username or user ID. The corresponding parameter of the response will always be the Twitch user ID.

When using filter_game, each element of the array must be a Twitch game name or game ID. The corresponding element of the response will always be the Twitch game ID(s).

HTTP Response

The response consists of a feed object.

Refer to Get Twitch Feeds for the full list of parameters.

Update Twitch Feed

HTTP Request Example

PATCH /feeds/62535fdab94a1c7f5e1d19f4 HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

{
    "webhook_options": {
        "filter_game": ["Just Chatting"],
        "filter_event": null
    }
}

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "62535fdab94a1c7f5e1d19f4",
    "feed_identifier": "92473777",
    "webhook_options": {
        "filter_game": [
            "509658"
        ],
        "filter_event": null,
        "custom_header": null,
        "webhook-name": null,
        "no-username-overwrite": false,
        "no-avatar-overwrite": false
    },
    "display_info": {
        "user_name": "discord",
        "display_name": "Discord",
        "user_url": "https://www.twitch.tv/discord",
        "game_names": null
    },
    "webhook_info": {
        "name": "GiselleBot Social Feeds",
        "avatar": null,
        "channel_id": "789481328328048660"
    }
}

This endpoint updates a feed in a server.

HTTP Request

PATCH https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/twitch/feeds/:feedId

You must send a body with the updated webhook_options object. Refer to Get Twitch Feeds for the full list of parameters. You cannot update the feed_identifier, webhook_channel or webhook_url for an existing feed.

HTTP Response

The response consists of a feed object.

Refer to Get Twitch Feeds for the full list of parameters.

Delete Twitch Feed

HTTP Request Example

DELETE /feeds/62535fdab94a1c7f5e1d19f4 HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}

This endpoint deletes a feed in a server.

HTTP Request

DELETE https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/twitch/feeds/:feedId

HTTP Response

The response consists of an atomic object, containing a success parameter (Boolean) indicating whether the feed was successfully deleted.

Twitter Connector

These endpoints control the Twitter Connector module.

Get Twitter User ID

HTTP Request Example

GET /getUserId/discord HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "userId": "3065618342",
    "userName": "discord",
    "displayName": "Discord"
}

This endpoint retrieves the ID of a Twitter user, given their username (i.e. the "@" name).

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/twitter/getUserId/:userName

HTTP Response

The response object contains the following parameters:

Parameter	Type	Description
userId	String	The ID of the Twitter user.
userName	String	The username of the Twitter user (i.e. the "@" name).
displayName	String	The full name of the Twitter user.

Get Twitter Feeds

HTTP Request Example

GET /feeds HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "feeds": [
        {
            "id": "5f4d61286ad9ee0df63dfed2",
            "feed_identifier": "783214",
            "webhook_options": {
                "filter_mode": "OR",
                "custom_header": null,
                "filter_words": null,
                "no-avatar-overwrite": true,
                "no-username-overwrite": true,
                "nsfw": null,
                "webhook-name": null,
                "filter_excl": false
            },
            "display_info": {
                "user_name": "Twitter",
                "display_name": "Twitter",
                "user_url": "https://twitter.com/Twitter"
            },
            "webhook_info": {
                "name": "Twitter Bot",
                "avatar": null,
                "channel_id": "487696731560214538"
            }
        },
        ...
    ]
}

This endpoint retrieves the list of feeds for a server.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/twitter/feeds

HTTP Response

The response contains the feeds array. Each element of the array has the following parameters:

Parameter	Type	Description
id	String	The feed unique ID.
feed_identifier	String	The feed-specific identifier.
webhook_options	Object	The feed-specific webhook options.
webhook_info	Object	The information about the webhook the feed is streaming to.

The webhook_options object contains the following parameters:

Parameter	Type	Description
filter_mode	String	The filter behavior when more than one word is added to the whitelist filter (`filter_words`). This can be either `AND` or `OR`.
nsfw	?String	The NSFW behavior to apply when posting items to the feed if they are deemed to be so. `null` means that the NSFW behavior is disabled. When populated, this can be either `censor`, `skip` or `only`.
filter_words	?Array<String>	An array of words to filter (i.e. whitelist or blacklist, depending on `filter_excl`) when posting items to the feed. `null` means that the filter is disabled.
filter_excl	Boolean	When set to `true`, items will be posted to the feed only if they do not contain the filtered word(s). When set to `false`, items will be posted to the feed only if they do contain the filtered word(s).
custom_header	?String	A custom template to use as message content when posting items to the feed. Custom headers can have a maximum of 1024 characters. `null` means that the default header will be used.
webhook-name	?String	A custom name to use as webhook name (i.e. author) when posting items to the feed. Custom names can have a maximum of 32 characters. `null` means that the default webhook name will be used.
no-username-overwrite	Boolean	When set to `true`, the webhook name defined within the "Integrations" section of Discord will not be overwritten by the default or custom webhook name.
no-avatar-overwrite	Boolean	When set to `true`, the webhook avatar defined within the "Integrations" section of Discord will not be overwritten by the default webhook avatar.

The display_info object contains the following parameters:

Parameter	Type	Description
user_name	String	The username of the Twitter user (i.e. the "@" name).
display_name	String	The full name of the Twitter user.
user_url	String	The profile URL of the Twitter user.

The webhook_info object contains the following parameters:

Parameter	Type	Description
name	String	The name of the webhook.
avatar	String	The avatar hash of the webhook.
channel_id	String	The ID of the channel the webhook belongs to.

Create Twitter Feed

HTTP Request Example

POST /feeds HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

{
    "feed_identifier": "discord",
    "webhook_channel": "598433171641729024",
    "webhook_options": {
        "no-avatar-overwrite": true
    }
}

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "62542ff494036b506e6d08bc",
    "feed_identifier": "3065618342",
    "webhook_options": {
        "filter_words": null,
        "filter_mode": "OR",
        "filter_excl": false,
        "nsfw": null,
        "custom_header": null,
        "webhook-name": null,
        "no-username-overwrite": false,
        "no-avatar-overwrite": true
    },
    "display_info": {
        "user_name": "Discord",
        "display_name": "discord",
        "user_url": "https://twitter.com/discord"
    },
    "webhook_info": {
        "name": "GiselleBot Social Feeds",
        "avatar": null,
        "channel_id": "598433171641729024"
    }
}

This endpoint creates a new feed in a server.

HTTP Request

POST https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/twitter/feeds

Request body parameters:

Parameter	Type	Required	Description
feed_identifier	String	true	The feed-specific identifier.
webhook_channel	String	true*	The ID of the channel the feed will be posted to. If the channel ID is specified, the bot will attempt to create a webhook in that channel (if a usable one isn't already present). At least one between `webhook_channel` and `webhook_url` must be filled.
webhook_url	String	true*	The URL of the webhook the feed will be posted to. At least one between `webhook_channel` and `webhook_url` must be filled.
webhook_options	Object	false	The options for the feed, as described in the corresponding object in Get Twitter Feeds. If you don't pass one or more options, or don't pass the whole object, default options will be used.

feed_identifier must be a Twitter username or user ID. The corresponding parameter of the response will always be the Twitter user ID.

HTTP Response

The response consists of a feed object.

Refer to Get Twitter Feeds for the full list of parameters.

Update Twitter Feed

HTTP Request Example

PATCH /feeds/62542ff494036b506e6d08bc HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

{
    "webhook_options": {
        "filter_words": ["transparency report"]
    }
}

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "62542ff494036b506e6d08bc",
    "feed_identifier": "3065618342",
    "webhook_options": {
        "filter_words": [
            "transparency report"
        ],
        "filter_mode": "OR",
        "filter_excl": false,
        "nsfw": null,
        "custom_header": null,
        "webhook-name": null,
        "no-username-overwrite": false,
        "no-avatar-overwrite": false
    },
    "display_info": {
        "user_name": "Discord",
        "display_name": "discord",
        "user_url": "https://twitter.com/discord"
    },
    "webhook_info": {
        "name": "GiselleBot Social Feeds",
        "avatar": null,
        "channel_id": "598433171641729024"
    }
}

This endpoint updates a feed in a server.

HTTP Request

PATCH https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/twitter/feeds/:feedId

You must send a body with the updated webhook_options object. Refer to Get Twitter Feeds for the full list of parameters. You cannot update the feed_identifier, webhook_channel or webhook_url for an existing feed.

HTTP Response

The response consists of a feed object.

Refer to Get Twitter Feeds for the full list of parameters.

Delete Twitter Feed

HTTP Request Example

DELETE /feeds/62542ff494036b506e6d08bc HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}

This endpoint deletes a feed in a server.

HTTP Request

DELETE https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/twitter/feeds/:feedId

HTTP Response

The response consists of an atomic object, containing a success parameter (Boolean) indicating whether the feed was successfully deleted.

YouTube Connector

These endpoints control the YouTube Connector module.

Get YouTube Channel ID

HTTP Request Example

GET /getUserId/discord HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "userId": "UCZ5XnGb-3t7jCkXdawN2tkA",
    "userName": "discord",
    "displayName": "Discord"
}

This endpoint retrieves the channel ID of a YouTube channel, given its title.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/youtube/getUserId/:userName

HTTP Response

The response object contains the following parameters:

Parameter	Type	Description
userId	String	The ID of the YouTube channel.
userName	String	The custom URL alias of the YouTube channel, if set. Otherwise, the ID of the YouTube channel.
displayName	String	The title of the YouTube channel.

Get YouTube Feeds

HTTP Request Example

GET /feeds HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "feeds": [
        {
            "id": "6254614394036b506e6d08c2",
            "feed_identifier": "UCPuGLlmOHLb2xwl82pxqHBA",
            "webhook_options": {
                "filter_event": [
                    "added"
                ],
                "filter_words": null,
                "filter_mode": "OR",
                "filter_excl": false,
                "nsfw": null,
                "custom_header": null,
                "webhook-name": null,
                "no-username-overwrite": false,
                "no-avatar-overwrite": false
            },
            "display_info": {
                "user_name": "UCPuGLlmOHLb2xwl82pxqHBA",
                "display_name": "GiselleBot",
                "user_url": "https://www.youtube.com/channel/UCPuGLlmOHLb2xwl82pxqHBA"
            },
            "webhook_info": {
                "name": "GiselleBot Social Feeds",
                "avatar": null,
                "channel_id": "598433171641729024"
            }
        },
        ...
    ]
}

This endpoint retrieves the list of feeds for a server.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/youtube/feeds

HTTP Response

The response contains the feeds array. Each element of the array has the following parameters:

Parameter	Type	Description
id	String	The feed unique ID.
feed_identifier	String	The feed-specific identifier.
webhook_options	Object	The feed-specific webhook options.
webhook_info	Object	The information about the webhook the feed is streaming to.

The webhook_options object contains the following parameters:

Parameter	Type	Description
filter_event	?Array<String>	An array of event types to filter (i.e. whitelist) when posting items to the feed. `null` means that the filter is disabled. When populated, this array can only contain one of these values: `added`, `updated`.
filter_mode	String	The filter behavior when more than one word is added to the whitelist filter (`filter_words`). This can be either `AND` or `OR`.
nsfw	?String	The NSFW behavior to apply when posting items to the feed if they are deemed to be so. `null` means that the NSFW behavior is disabled. When populated, this can be either `censor`, `skip` or `only`.
filter_words	?Array<String>	An array of words to filter (i.e. whitelist or blacklist, depending on `filter_excl`) when posting items to the feed. `null` means that the filter is disabled.
filter_excl	Boolean	When set to `true`, items will be posted to the feed only if they do not contain the filtered word(s). When set to `false`, items will be posted to the feed only if they do contain the filtered word(s).
custom_header	?String	A custom template to use as message content when posting items to the feed. Custom headers can have a maximum of 1024 characters. `null` means that the default header will be used.
webhook-name	?String	A custom name to use as webhook name (i.e. author) when posting items to the feed. Custom names can have a maximum of 32 characters. `null` means that the default webhook name will be used.
no-username-overwrite	Boolean	When set to `true`, the webhook name defined within the "Integrations" section of Discord will not be overwritten by the default or custom webhook name.
no-avatar-overwrite	Boolean	When set to `true`, the webhook avatar defined within the "Integrations" section of Discord will not be overwritten by the default webhook avatar.

The display_info object contains the following parameters:

Parameter	Type	Description
user_name	String	The custom URL alias of the YouTube channel, if set. Otherwise, the ID of the YouTube channel.
display_name	String	The title of the YouTube channel.
user_url	String	The URL of the YouTube channel.

The webhook_info object contains the following parameters:

Parameter	Type	Description
name	String	The name of the webhook.
avatar	String	The avatar hash of the webhook.
channel_id	String	The ID of the channel the webhook belongs to.

Create YouTube Feed

HTTP Request Example

POST /feeds HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

{
    "feed_identifier": "discord",
    "webhook_channel": "598433171641729024",
    "webhook_options": {
        "filter_event": ["added"]
    }
}

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "625461a794036b506e6d08c4",
    "feed_identifier": "UCZ5XnGb-3t7jCkXdawN2tkA",
    "webhook_options": {
        "filter_event": [
            "added"
        ],
        "filter_words": null,
        "filter_mode": "OR",
        "filter_excl": false,
        "nsfw": null,
        "custom_header": null,
        "webhook-name": null,
        "no-username-overwrite": false,
        "no-avatar-overwrite": false
    },
    "display_info": {
        "user_name": "discord",
        "display_name": "Discord",
        "user_url": "https://www.youtube.com/discord"
    },
    "webhook_info": {
        "name": "GiselleBot Social Feeds",
        "avatar": null,
        "channel_id": "598433171641729024"
    }
}

This endpoint creates a new feed in a server.

HTTP Request

POST https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/youtube/feeds

Request body parameters:

Parameter	Type	Required	Description
feed_identifier	String	true	The feed-specific identifier.
webhook_channel	String	true*	The ID of the channel the feed will be posted to. If the channel ID is specified, the bot will attempt to create a webhook in that channel (if a usable one isn't already present). At least one between `webhook_channel` and `webhook_url` must be filled.
webhook_url	String	true*	The URL of the webhook the feed will be posted to. At least one between `webhook_channel` and `webhook_url` must be filled.
webhook_options	Object	false	The options for the feed, as described in the corresponding object in Get YouTube Feeds. If you don't pass one or more options, or don't pass the whole object, default options will be used.

feed_identifier must be a YouTube channel title (unreliable) or channel ID. The corresponding parameter of the response will always be the YouTube channel ID.

HTTP Response

The response consists of a feed object.

Refer to Get YouTube Feeds for the full list of parameters.

Update YouTube Feed

HTTP Request Example

PATCH /feeds/625461a794036b506e6d08c4 HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

{
    "webhook_options": {
        "no-username-overwrite": true
    }
}

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "625461a794036b506e6d08c4",
    "feed_identifier": "UCZ5XnGb-3t7jCkXdawN2tkA",
    "webhook_options": {
        "filter_event": null,
        "filter_words": null,
        "filter_mode": "OR",
        "filter_excl": false,
        "nsfw": null,
        "custom_header": null,
        "webhook-name": null,
        "no-username-overwrite": true,
        "no-avatar-overwrite": false
    },
    "display_info": {
        "user_name": "discord",
        "display_name": "Discord",
        "user_url": "https://www.youtube.com/discord"
    },
    "webhook_info": {
        "name": "GiselleBot Social Feeds",
        "avatar": null,
        "channel_id": "598433171641729024"
    }
}

This endpoint updates a feed in a server.

HTTP Request

PATCH https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/youtube/feeds/:feedId

You must send a body with the updated webhook_options object. Refer to Get YouTube Feeds for the full list of parameters. You cannot update the feed_identifier, webhook_channel or webhook_url for an existing feed.

HTTP Response

The response consists of a feed object.

Refer to Get YouTube Feeds for the full list of parameters.

Delete YouTube Feed

HTTP Request Example

DELETE /feeds/625461a794036b506e6d08c4 HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}

This endpoint deletes a feed in a server.

HTTP Request

DELETE https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/youtube/feeds/:feedId

HTTP Response

The response consists of an atomic object, containing a success parameter (Boolean) indicating whether the feed was successfully deleted.

Rate Limits

The API has two different rate limiting counters:

The /api endpoints are limited to 120 requests per 1 minute.
The /auth endpoints are limited to 120 requests per 1 hour.

Errors

The API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your access token is wrong, or invalid.
403	Forbidden -- The requested resource is not available with the available authorization rights.
404	Not Found -- The specified resource could not be found.
408	Request Timeout -- The request took too long. Please, try again.
415	Unsupported Media Type -- The specified media is not supported (reserved to specific API services).
429	Too Many Requests -- You're sending too many requests! Slow down!
500	Internal Server Error -- We had a problem with our server. Please, try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please, try again later.

The error body will contain an errors parameter, of

The error response contains the errors array. This array will usually be of length 1, but may contain more elements in specific cases. Each element of the array has the following parameters:

Parameter	Type	Description
code	String	A short string describing the error. This is usually the human-readable version of the corresponding HTTP code.
message	String	A longer string describing the error. This usually contains more useful information about what happened.
additionalProperties	Object	In some cases, more data may be passed to the client. This data will be contained within this object.