From 5aea2b4df85c7e1e3917b20dc18e13c5c0c1a6b3 Mon Sep 17 00:00:00 2001 From: Erik Bigler Date: Sat, 11 Jan 2025 15:54:11 -0600 Subject: [PATCH] feat: finish updating api pages to use fancier components --- src/app/v5/dev/api/contacts/page.mdx | 1592 ----------------- src/app/v5/dev/api/counters/page.mdx | 192 +- src/app/v5/dev/api/currency/page.mdx | 286 +-- src/app/v5/dev/api/custom-roles/page.mdx | 363 ++-- src/app/v5/dev/api/custom-variables/page.mdx | 168 +- src/app/v5/dev/api/effect-queues/page.mdx | 338 ++-- src/app/v5/dev/api/effects/page.mdx | 6 +- src/app/v5/dev/api/endpoints/page.mdx | 1 - src/app/v5/dev/api/oauth/page.mdx | 8 +- src/app/v5/dev/api/quotes/page.mdx | 468 ++--- src/app/v5/dev/api/replace-variables/page.mdx | 139 +- src/app/v5/dev/api/status/page.mdx | 8 +- src/app/v5/dev/api/timers/page.mdx | 264 ++- src/app/v5/dev/api/viewers/page.mdx | 584 ++++-- 14 files changed, 1679 insertions(+), 2738 deletions(-) delete mode 100644 src/app/v5/dev/api/contacts/page.mdx delete mode 100644 src/app/v5/dev/api/endpoints/page.mdx diff --git a/src/app/v5/dev/api/contacts/page.mdx b/src/app/v5/dev/api/contacts/page.mdx deleted file mode 100644 index dafa5f8..0000000 --- a/src/app/v5/dev/api/contacts/page.mdx +++ /dev/null @@ -1,1592 +0,0 @@ -## Table Of Contents - -- [Overview](#overview) -- [Rest Endpoints](#endpoints) - - Auth - - [**/auth** `GET`](#get-auth) - - [**/auth/callback2** `GET`](#get-authcallback2) - - [**/auth/tokencallback** `GET`](#get-authtokencallback) - - Status - - [**/status** `GET`](#get-status) - - Effects - - [**/effects** `GET`](#get-effects) - - [**/effects** `POST`](#post-effects) - - [**/effects/preset** `GET`](#get-effectspreset) - - [**/effects/:effectId** `GET`](#get-effectseffectid) - - [**/effects/preset/:presetListId** `GET`](#get-effectspresetpresetlistid) - - [**/effects/preset/:presetListId** `POST`](#post-effectspresetpresetlistid) - - [**/effects/preset/:presetListId/run** `GET`](#get-effectspresetpresetlistidrun) - - [**/effects/preset/:presetListId/run** `POST`](#post-effectspresetpresetlistidrun) - - Fonts - - [**/fonts** `GET`](#get-fonts) - - [**/fonts/:name** `GET`](#get-fontsname) - - Custom-variables - - [**/custom-variables** `GET`](#get-custom-variables) - - [**/custom-variables/:variableName** `GET`](#get-custom-variablesvariablename) - - [**/custom-variables/:variableName** `POST`](#post-custom-variablesvariablename) - - Variables - - [**/variables** `GET`](#get-variables) - - Viewers - - [**/viewers** `GET`](#get-viewers) - - [**/viewers/export** `GET`](#get-viewersexport) - - [**/viewers/:userId** `GET`](#get-viewersuserid) - - [**/viewers/:userId/metadata/:metadataKey** `POST`](#post-viewersuseridmetadatametadatakey) - - [**/viewers/:userId/metadata/:metadataKey** `PUT`](#put-viewersuseridmetadatametadatakey) - - [**/viewers/:userId/metadata/:metadataKey** `DELETE`](#delete-viewersuseridmetadatametadatakey) - - [**/viewers/:userId/currency** `GET`](#get-viewersuseridcurrency) - - [**/viewers/:userId/currency/:currencyId** `GET`](#get-viewersuseridcurrencycurrencyid) - - [**/viewers/:userId/currency/:currencyId** `POST`](#post-viewersuseridcurrencycurrencyid) - - [**/viewers/:userId/customRoles** `GET`](#get-viewersuseridcustomroles) - - [**/viewers/:userId/customRoles/:customRoleId** `POST`](#post-viewersuseridcustomrolescustomroleid) - - [**/viewers/:userId/customRoles/:customRoleId** `DELETE`](#delete-viewersuseridcustomrolescustomroleid) - - CustomRoles - - [**/customRoles** `GET`](#get-customroles) - - [**/customRoles/:customRoleId** `GET`](#get-customrolescustomroleid) - - [**/customRoles/:customRoleId/clear** `GET`](#get-customrolescustomroleidclear) - - [**/customRoles/:customRoleId/viewer/:userId** `POST`](#post-customrolescustomroleidvieweruserid) - - [**/customRoles/:customRoleId/viewer/:userId** `DELETE`](#delete-customrolescustomroleidvieweruserid) - - Currency - - [**/currency** `GET`](#get-currency) - - [**/currency/:currencyName** `GET`](#get-currencycurrencyname) - - [**/currency/:currencyName/top** `GET`](#get-currencycurrencynametop) - - Quotes - - [**/quotes** `GET`](#get-quotes) - - [**/quotes** `POST`](#post-quotes) - - [**/quotes/:quoteId** `GET`](#get-quotesquoteid) - - [**/quotes/:quoteId** `PUT`](#put-quotesquoteid) - - [**/quotes/:quoteId** `PATCH`](#patch-quotesquoteid) - - [**/quotes/:quoteId** `DELETE`](#delete-quotesquoteid) - - Counters - - [**/counters** `GET`](#get-counters) - - [**/counters/:counterId** `GET`](#get-counterscounterid) - - [**/counters/:counterId** `POST`](#post-counterscounterid) - - Timers - - [**/timers** `GET`](#get-timers) - - [**/timers/:timerId** `GET`](#get-timerstimerid) - - [**/timers/:timerId/:action** `GET`](#get-timerstimeridaction) - - Queues - - [**/queues** `GET`](#get-queues) - - [**/queues/:queueId** `GET`](#get-queuesqueueid) - - [**/queues/:queueId/pause** `GET`](#get-queuesqueueidpause) - - [**/queues/:queueId/pause** `POST`](#post-queuesqueueidpause) - - [**/queues/:queueId/resume** `GET`](#get-queuesqueueidresume) - - [**/queues/:queueId/resume** `POST`](#post-queuesqueueidresume) - - [**/queues/:queueId/toggle** `GET`](#get-queuesqueueidtoggle) - - [**/queues/:queueId/toggle** `POST`](#post-queuesqueueidtoggle) - - [**/queues/:queueId/clear** `GET`](#get-queuesqueueidclear) - - [**/queues/:queueId/clear** `POST`](#post-queuesqueueidclear) -- [WebSocket Endpoint](#websocket-endpoint) - -## Overview - -Firebot hosts a local API that developers can use to get data from Firebot or tell it to run effects. - -- The API is hosted on port **7472**. All endpoints have the root **http://localhost:7472/api/v1** -- All responses are in JSON. -- Don't forget that Firebot must be running for the API to be available. - -## Rest Endpoints - -## Authentication - -### `GET /auth` - -#### Description: - -Redirects the user to the authorization URI of the specified authentication provider. - -#### Query Parameters: - -- `providerId` `string`: The ID of the authentication provider. - -#### Example Request (URL): - -``` -GET /auth?providerId=google -``` - -#### Example Response (Redirect): - -This will redirect the user to the authorization URI of the specified provider (e.g., Google OAuth2 authorization page). - -```http -HTTP/1.1 302 Found -Location: https://accounts.google.com/o/oauth2/auth?client_id=...&redirect_uri=...&response_type=code&scope=... -``` - -### `GET /auth/callback2` - -#### Description: - -Callback endpoint for authentication providers after user authorization. It exchanges the authorization code or token -for an access token. - -#### Query Parameters: - -- `state` `string`: The provider ID passed in the initial authentication request, used to identify the provider. - -#### Example Request (URL): - -``` -GET /auth/callback2?state=google&code=authorizationCodeHere -``` - -#### Example Response (Redirect): - -Upon success, redirects to the login success page. - -```http -HTTP/1.1 302 Found -Location: /loginsuccess?provider=google -``` - -#### Example Response (Error): - -If the `state` parameter is invalid or missing, returns an error response. - -```json -{ - "error": "Invalid provider id in state" -} -``` - -If the authentication fails (e.g., invalid token exchange or an OAuth error), the response will be: - -```json -{ - "error": "Authentication failed" -} -``` - -## Status - -### `GET /status` - -#### Description: - -Fetches the current status of the application's connections, specifically the chat connection status. - -#### Example Response (JSON): - -```json -{ - "connections": { - "chat": true - } -} -``` - -## Effects - -### `GET /effects` - -#### Description: - -Fetches all available effect definitions. Optionally, filters them by trigger type if the `trigger` query parameter is -provided. - -#### Query Parameters: - -- `trigger` `string: optional`: The type of trigger to filter the effects by. - -#### Example Request (URL): - -``` -GET /effects?trigger=someTriggerType -``` - -#### Example Response (JSON): - -```json -[ - { - "id": "effect1", - "name": "Effect 1", - "description": "Description of effect 1", - "triggers": ["someTriggerType"] - }, - { - "id": "effect2", - "name": "Effect 2", - "description": "Description of effect 2" - } -] -``` - -### `GET /effects/:effectId` - -#### Description: - -Fetches the details of a specific effect by its `effectId`. - -#### URL Parameters: - -- `effectId` `string`: The ID of the effect to fetch. - -#### Example Request (URL): - -``` -GET /effects/effect1 -``` - -#### Example Response (JSON): - -```json -{ - "id": "effect1", - "name": "Effect 1", - "description": "Description of effect 1", - "triggers": ["someTriggerType"] -} -``` - -#### Example Response (Error): - -```json -{ - "status": "error", - "message": "Cannot find effect 'effect1'" -} -``` - -### `POST /effects` - -#### Description: - -Triggers one or more effects with optional trigger data. Requires a request body containing an array of effects to run. - -#### Request Body (JSON): - -```json -{ - "effects": [{ "id": "effect1" }, { "id": "effect2" }], - "triggerData": { - "username": "API Call" - } -} -``` - -#### Example Response (Success): - -```json -{ - "status": "success" -} -``` - -#### Example Response (Error): - -```json -{ - "status": "error", - "message": "No effects provided." -} -``` - -### `GET /effects/preset` - -#### Description: - -Fetches a list of all preset effect lists, including their IDs and associated arguments. - -#### Example Response (JSON): - -```json -[ - { - "id": "preset1", - "name": "Preset 1", - "args": ["arg1", "arg2"] - }, - { - "id": "preset2", - "name": "Preset 2", - "args": ["arg1"] - } -] -``` - -### `GET /effects/preset/:presetListId` - -#### Description: - -Runs the specified preset effect list synchronously (i.e., waits for the effects to complete before responding). - -#### URL Parameters: - -- `presetListId` `string`: The ID of the preset effect list to run. - -#### Example Request (URL): - -``` -GET /effects/preset/preset1 -``` - -#### Example Response (Success): - -```json -{ - "status": "success" -} -``` - -#### Example Response (Error): - -```json -{ - "status": "error", - "message": "Cannot find preset effect list 'preset1'" -} -``` - -### `POST /effects/preset/:presetListId` - -#### Description: - -Runs the specified preset effect list synchronously with optional arguments and username. - -#### URL Parameters: - -- `presetListId` `string`: The ID of the preset effect list to run. - -#### Request Body (JSON): - -```json -{ - "username": "testuser", - "args": { "arg1": "value1", "arg2": "value2" } -} -``` - -#### Example Response (Success): - -```json -{ - "status": "success" -} -``` - -#### Example Response (Error): - -```json -{ - "status": "error", - "message": "Cannot find preset effect list 'preset1'" -} -``` - -### `GET /effects/preset/:presetListId/run` - -#### Description: - -Triggers the specified preset effect list asynchronously (i.e., doesn't wait for the effects to complete). - -#### URL Parameters: - -- `presetListId` `string`: The ID of the preset effect list to run. - -#### Example Request (URL): - -``` -GET /effects/preset/preset1/run -``` - -#### Example Response (Success): - -```json -{ - "status": "success" -} -``` - -#### Example Response (Error): - -```json -{ - "status": "error", - "message": "Cannot find preset effect list 'preset1'" -} -``` - -### `POST /effects/preset/:presetListId/run` - -#### Description: - -Triggers the specified preset effect list asynchronously with optional arguments and username. - -#### URL Parameters: - -- `presetListId` `string`: The ID of the preset effect list to run. - -#### Request Body (JSON): - -```json -{ - "username": "testuser", - "args": { "arg1": "value1", "arg2": "value2" } -} -``` - -#### Example Response (Success): - -```json -{ - "status": "success" -} -``` - -#### Example Response (Error): - -```json -{ - "status": "error", - "message": "Cannot find preset effect list 'preset1'" -} -``` - -## Fonts - -### `GET /fonts` - -#### Description: - -Fetches a list of all installed fonts, including their names and formats. - -#### Example Response (JSON): - -```json -[ - { - "name": "Arial", - "format": "TrueType" - }, - { - "name": "Helvetica", - "format": "OpenType" - } -] -``` - -### `GET /fonts/:name` - -#### Description: - -Fetches the font file for a specific font by its name. Returns the font file if it exists on the server. - -#### URL Parameters: - -- `name` `string`: The name of the font to fetch. - -#### Example Request (URL): - -``` -GET /fonts/Arial -``` - -#### Example Response (File): - -The server will send the font file (e.g., `.ttf` or `.otf`) in response. This will be handled by the browser, which may -download or render the font depending on its capabilities. - -#### Example Response (Error): - -If the font is not found: - -```json -{ - "status": "error", - "message": "/fonts/Arial not found" -} -``` - -## Custom Variables - -### `GET /custom-variables` - -#### Description: - -Fetches all custom variables in the system. - -#### Example Response (JSON): - -```json -[ - { - "name": "var1", - "data": "some data", - "ttl": 3600 - }, - { - "name": "var2", - "data": "more data", - "ttl": 0 - } -] -``` - -### `GET /custom-variables/:variableName` - -#### Description: - -Fetches the value of a specific custom variable by its `variableName`. - -#### URL Parameters: - -- `variableName` `string`: The name of the custom variable to retrieve. - -#### Example Request (URL): - -``` -GET /custom-variables/var1 -``` - -#### Example Response (JSON): - -```json -{ - "name": "var1", - "data": "some data", - "ttl": 3600 -} -``` - -### `POST /custom-variables/:variableName` - -#### Description: - -Sets a custom variable by its `variableName`. The request body should contain the data and optional TTL (time-to-live) -for the variable. - -#### URL Parameters: - -- `variableName` `string`: The name of the custom variable to set. - -#### Request Body (JSON): - -```json -{ - "data": "new value", - "ttl": 3600 -} -``` - -#### Example Response (Success): - -```json -{ - "status": "success" -} -``` - -#### Example Response (Error): - -```json -{ - "status": "error", - "message": "No data provided" -} -``` - -## Variables - -### `GET /variables` - -#### Description: - -Fetches a list of all replace variables, sorted by their `handle` value. - -#### Example Response (JSON): - -```json -[ - { - "definition": { - "handle": "example_variable_name", - "aliases": ["alias1", "alias2"], - "usage": "Example usage description", - "description": "Example variable definition description", - "examples": [ - { - "usage": "example usage 1", - "description": "Example description 1" - }, - { - "usage": "example usage 2", - "description": "Example description 2" - } - ], - "categories": [ - "common", - "trigger based", - "user based", - "text", - "numbers", - "advanced", - "obs", - "integrations" - ], - "triggers": { - "command": true, - "custom_script": true, - "startup_script": false, - "api": true, - "event": ["event1", "event2"], - "hotkey": false, - "timer": true, - "counter": false, - "preset": true, - "quick_action": false, - "manual": true - }, - "possibleDataOutput": [ - "null", - "bool", - "number", - "text", - "array", - "object", - "ALL" - ], - "hidden": false, - "spoof": true - }, - "handle": "ALL" - } -] -``` - -## Custom Roles API - -### `GET /customRoles` - -#### Description: - -Fetches a list of all custom roles with the associated viewers. - -#### Example Response (JSON): - -```json -[ - { - "id": "role1", - "name": "Moderator", - "viewers": ["viewer1", "viewer2"] - }, - { - "id": "role2", - "name": "VIP", - "viewers": ["viewer3"] - } -] -``` - ---- - -### `GET /customRoles/:customRoleId` - -#### Description: - -Fetches a specific custom role by its ID. Returns role details and the list of viewers associated with it. - -#### Example Response (JSON): - -```json -{ - "id": "role1", - "name": "Moderator", - "viewers": ["viewer1", "viewer2"] -} -``` - -#### Example Error Response (if the role does not exist): - -```json -{ - "status": "error", - "message": "Custom role 'role1' not found" -} -``` - ---- - -### `POST /customRoles/:customRoleId/viewer/:userId` - -#### Description: - -Adds a user to a custom role. You can specify the user by either `userId` or `username` via query parameter. - -#### Request Parameters: - -- `customRoleId`: The ID of the custom role to which the user is being added. -- `userId`: The ID of the viewer to be added to the role. - -#### Query Parameter: - -- `username`: Set to "true" if the user should be found by `username` instead of `userId`. - -#### Example Request (URL): - -``` -POST /customRoles/role1/viewer/viewer1?username=true -``` - -#### Example Success Response: - -```json -{ - "status": "success", - "message": "Viewer added to custom role" -} -``` - -#### Example Error Response (if user or custom role does not exist): - -```json -{ - "status": "error", - "message": "Specified viewer does not exist" -} -``` - ---- - -### `DELETE /customRoles/:customRoleId/viewer/:userId` - -#### Description: - -Removes a user from a custom role. You can specify the user by either `userId` or `username` via query parameter. - -#### Request Parameters: - -- `customRoleId`: The ID of the custom role to which the user is being removed from. -- `userId`: The ID of the viewer to be removed from the role. - -#### Query Parameter: - -- `username`: Set to "true" if the user should be found by `username` instead of `userId`. - -#### Example Request (URL): - -``` -DELETE /customRoles/role1/viewer/viewer1?username=true -``` - -#### Example Success Response: - -```json -{ - "status": "success", - "message": "Viewer removed from custom role" -} -``` - -#### Example Error Response (if user or custom role does not exist): - -```json -{ - "status": "error", - "message": "Specified viewer does not exist" -} -``` - ---- - -### `DELETE /customRoles/:customRoleId/clear` - -#### Description: - -Removes all viewers from a custom role. - -#### Request Parameters: - -- `customRoleId`: The ID of the custom role from which all viewers are being removed. - -#### Example Request (URL): - -``` -DELETE /customRoles/role1/clear -``` - -#### Example Success Response: - -```json -{ - "status": "success", - "message": "All viewers removed from the custom role" -} -``` - -#### Example Error Response (if custom role does not exist): - -```json -{ - "status": "error", - "message": "Specified custom role does not exist" -} -``` - -## Currency API - -### `GET /currencies/:currencyName?` - -#### Description: - -Fetches currency data for a specific currency or all currencies if no currency name is provided. - -- If `currencyName` is specified, it will return data for the specified currency. -- If `currencyName` is not provided, it will return a list of all currencies. - -#### Example Request (for a specific currency): - -``` -GET /currencies/coin -``` - -#### Example Response (for a specific currency): - -```json -{ - "d073da00-a726-11e9-a874-7de9c8544807": { - "id": "d073da00-a726-11e9-a874-7de9c8544807", - "name": "coin", - "active": true, - "payout": 5, - "interval": 5, - "limit": 1000000, - "transfer": "Allow", - "bonus": {}, - "offline": 5, - "$$hashKey": "object:35427" - } -} -``` - -#### Example Request (for all currencies): - -``` -GET /currencies -``` - -#### Example Response (for all currencies): - -```json -[ - { - "d073da00-a726-11e9-a874-7de9c8544807": { - "id": "d073da00-a726-11e9-a874-7de9c8544807", - "name": "coin", - "active": true, - "payout": 5, - "interval": 5, - "limit": 1000000, - "transfer": "Allow", - "bonus": {}, - "offline": 5, - "$$hashKey": "object:35427" - } - }, - { - "d073da00-a726-11e9-a874-7de9c8544807": { - "id": "d073da00-a726-11e9-a874-7de9c8544807", - "name": "pups", - "active": true, - "payout": 5, - "interval": 5, - "limit": 1000000, - "transfer": "Allow", - "bonus": {}, - "offline": 5, - "$$hashKey": "object:35427" - } - } -] -``` - ---- - -### `GET /currencies/:currencyName/topHolders` - -#### Description: - -Fetches the top holders of a specific currency. By default, it will return the top 10 holders, but you can specify a -`count` query parameter to change the number of top holders returned. - -#### Request Parameters: - -- `currencyName`: The name of the currency (e.g., "coin", "pups"). -- `count`: (Optional) The number of top holders to return. If not specified, defaults to 10. - -#### Example Request (with `count` query parameter): - -``` -GET /currencies/pups/topHolders?count=2 - -``` - -#### Example Response: - -```json -[ - { - "username": "fluffypanda", - "displayName": "FluffyPanda", - "currency": { - "d073da00-a726-11e9-a874-7de9c8544807": 281272, - "3eba5d80-4297-11ee-86eb-d7d7d2938882": 103665 - }, - "_id": "90448736" - }, - { - "username": "sparklenova", - "displayName": "SparkleNova", - "currency": { - "d073da00-a726-11e9-a874-7de9c8544807": 281272, - "3eba5d80-4297-11ee-86eb-d7d7d2938882": 103665 - }, - "_id": "90448726" - } -] -``` - -#### Example Request (default 10 top holders): - -``` -GET /currencies/coin/topHolders -``` - -#### Example Response (default top 10 holders): - -```json -[ - { - "username": "fluffypanda", - "displayName": "FluffyPanda", - "currency": { - "d073da00-a726-11e9-a874-7de9c8544807": 281272, - "3eba5d80-4297-11ee-86eb-d7d7d2938882": 103665 - }, - "_id": "90448736" - }, - { - "username": "sparklenova", - "displayName": "SparkleNova", - "currency": { - "d073da00-a726-11e9-a874-7de9c8544807": 281272, - "3eba5d80-4297-11ee-86eb-d7d7d2938882": 103665 - }, - "_id": "90448726" - } - // More users... -] -``` - -## Quotes API - -### `GET /quotes` - -#### Description: - -Fetches all available quotes. - -#### Example Request: - -``` -GET /quotes -``` - -#### Example Response: - -```json -[ - { - "id": 1, - "text": "This is a sample quote.", - "originator": "John Doe", - "creator": "Jane Smith", - "game": "Game Name", - "createdAt": "2024-12-14T00:00:00Z" - }, - { - "id": 2, - "text": "Another quote here.", - "originator": "Alice", - "creator": "Bob", - "game": "Another Game", - "createdAt": "2024-12-13T00:00:00Z" - } -] -``` - ---- - -### `GET /quotes/:quoteId` - -#### Description: - -Fetches a specific quote by its `quoteId`. - -#### Request Parameters: - -- `quoteId`: The unique identifier of the quote. - -#### Example Request: - -``` -GET /quotes/1 -``` - -#### Example Response: - -```json -{ - "id": 1, - "text": "This is a sample quote.", - "originator": "John Doe", - "creator": "Jane Smith", - "game": "Game Name", - "createdAt": "2024-12-14T00:00:00Z" -} -``` - ---- - -### `POST /quotes` - -#### Description: - -Creates a new quote. - -#### Request Body: - -- `text`: The text content of the quote (required). -- `originator`: The person who originated the quote (required). -- `creator`: The creator of the quote (required). -- `game`: The game context (optional). - -#### Example Request: - -```json -{ - "text": "This is a new quote.", - "originator": "Alice", - "creator": "Bob", - "game": "Sample Game" -} -``` - -#### Example Response: - -```json -{ - "id": 3, - "text": "This is a new quote.", - "originator": "Alice", - "creator": "Bob", - "game": "Sample Game", - "createdAt": "2024-12-14T00:00:00Z" -} -``` - ---- - -### `PUT /quotes/:quoteId` - -#### Description: - -Creates or updates a specific quote. If a quote with the provided `quoteId` does not exist, it will be created; -otherwise, it will be updated. - -#### Request Parameters: - -- `quoteId`: The unique identifier of the quote to be updated or created. - -#### Request Body: - -- `text`: The text content of the quote (required). -- `originator`: The person who originated the quote (required). -- `creator`: The creator of the quote (required). -- `game`: The game context (optional). -- `createdAt`: The creation date (optional). - -#### Example Request: - -```json -{ - "text": "Updated quote content", - "originator": "Alice", - "creator": "Bob", - "game": "Sample Game", - "createdAt": "2024-12-14T00:00:00Z" -} -``` - -#### Example Response: - -```json -{ - "id": 1, - "text": "Updated quote content", - "originator": "Alice", - "creator": "Bob", - "game": "Sample Game", - "createdAt": "2024-12-14T00:00:00Z" -} -``` - ---- - -### `PATCH /quotes/:quoteId` - -#### Description: - -Partially updates an existing quote. You can update specific fields such as `text`, `originator`, `creator`, `game`, or -`createdAt`. - -#### Request Parameters: - -- `quoteId`: The unique identifier of the quote to be updated. - -#### Request Body: - -Any of the following fields can be included: - -- `text`: The text content of the quote. -- `originator`: The person who originated the quote. -- `creator`: The creator of the quote. -- `game`: The game context. -- `createdAt`: The creation date. - -#### Example Request: - -```json -{ - "text": "Partially updated quote content", - "originator": "Alice" -} -``` - -#### Example Response: - -```json -{ - "id": 1, - "text": "Partially updated quote content", - "originator": "Alice", - "creator": "Bob", - "game": "Sample Game", - "createdAt": "2024-12-14T00:00:00Z" -} -``` - ---- - -### `DELETE /quotes/:quoteId` - -#### Description: - -Deletes a specific quote by its `quoteId`. - -#### Request Parameters: - -- `quoteId`: The unique identifier of the quote to be deleted. - -#### Example Request: - -``` -DELETE /quotes/1 - -``` - -#### Example Response: - -``` -HTTP Status 204 No Content -``` - -## Counters API - -### `GET /counters` - -#### Description: - -Fetches all available counters. - -#### Example Request: - -``` -GET /counters -``` - -#### Example Response: - -```json -[ - { - "id": "counter1", - "name": "Counter 1", - "value": 10 - }, - { - "id": "counter2", - "name": "Counter 2", - "value": 15 - } -] -``` - ---- - -### `GET /counters/:counterId` - -#### Description: - -Fetches a specific counter by its `counterId`. - -#### Request Parameters: - -- `counterId`: The unique identifier of the counter. - -#### Example Request: - -``` -GET /counters/counter1 -``` - -#### Example Response: - -```json -{ - "id": "counter1", - "name": "Counter 1", - "value": 10 -} -``` - ---- - -### `POST /counters/:counterId` - -#### Description: - -Updates the value of an existing counter. Optionally, you can override the current value. - -#### Request Parameters: - -- `counterId`: The unique identifier of the counter to be updated. - -#### Request Body: - -- `value`: The new value to set for the counter (required). -- `override`: A boolean indicating whether to override the counter's current value (optional, defaults to `false`). - -#### Example Request: - -```json -{ - "value": 20, - "override": true -} -``` - -#### Example Response: - -```json -{ - "oldValue": 10, - "newValue": 20 -} -``` - -## Timers API - -### `GET /timers` - -#### Description: - -Fetches all available timers. - -#### Example Request: - -``` -GET /timers -``` - -#### Example Response: - -```json -[ - { - "id": "timer1", - "name": "Timer 1", - "active": true - }, - { - "id": "timer2", - "name": "Timer 2", - "active": false - } -] -``` - ---- - -### `GET /timers/:timerId` - -#### Description: - -Fetches a specific timer by its `timerId`. - -#### Request Parameters: - -- `timerId`: The unique identifier of the timer. - -#### Example Request: - -``` -GET /timers/timer1 -``` - -#### Example Response: - -```json -{ - "id": "timer1", - "name": "Timer 1", - "active": true -} -``` - ---- - -### `POST /timers/:timerId/:action` - -#### Description: - -Performs an action on the specified timer. - -#### Request Parameters: - -- `timerId`: The unique identifier of the timer to be modified. -- `action`: The action to perform on the timer. Can be one of the following: -- `enable`: Enables the timer. -- `disable`: Disables the timer. -- `toggle`: Toggles the active state of the timer. -- `clear`: Clears the timer's interval. - -#### Example Request: - -``` -POST /timers/timer1/enable -``` - -#### Example Response: - -```json -{ - "status": "success", - "message": "Timer enabled" -} -``` - -#### Example Request: - -``` -POST /timers/timer1/clear -``` - -#### Example Response: - -```json -{ - "status": "success", - "message": "Timer interval cleared" -} -``` - -## Effect Queue API - -### `GET /queues` - -#### Description: - -Fetches all available effect queues. - -#### Example Request: - -``` -GET /queues -``` - -#### Example Response: - -```json -[ - { - "id": "queue1", - "name": "Queue 1", - "status": "active" - }, - { - "id": "queue2", - "name": "Queue 2", - "status": "paused" - } -] -``` - ---- - -### `GET /queues/:queueId` - -#### Description: - -Fetches a specific effect queue by its `queueId`. - -#### Request Parameters: - -- `queueId`: The unique identifier of the queue. - -#### Example Request: - -``` -GET /queues/queue1 -``` - -#### Example Response: - -```json -{ - "id": "queue1", - "name": "Queue 1", - "status": "active" -} -``` - ---- - -### `POST /queues/:queueId/pause` - -#### Description: - -Pauses the specified effect queue. - -#### Request Parameters: - -- `queueId`: The unique identifier of the queue to be paused. - -#### Example Request: - -``` -POST /queues/queue1/pause -``` - -#### Example Response: - -```json -{ - "id": "queue1", - "name": "Queue 1", - "status": "paused" -} -``` - ---- - -### `POST /queues/:queueId/resume` - -#### Description: - -Resumes the specified effect queue. - -#### Request Parameters: - -- `queueId`: The unique identifier of the queue to be resumed. - -#### Example Request: - -``` -POST /queues/queue1/resume -``` - -#### Example Response: - -```json -{ - "id": "queue1", - "name": "Queue 1", - "status": "active" -} -``` - ---- - -### `POST /queues/:queueId/toggle` - -#### Description: - -Toggles the status of the specified effect queue (pauses if active, resumes if paused). - -#### Request Parameters: - -- `queueId`: The unique identifier of the queue to be toggled. - -#### Example Request: - -``` -POST /queues/queue1/toggle -``` - -#### Example Response: - -```json -{ - "id": "queue1", - "name": "Queue 1", - "status": "paused" -} -``` - ---- - -### `POST /queues/:queueId/clear` - -#### Description: - -Clears the specified effect queue (removes the queue). - -#### Request Parameters: - -- `queueId`: The unique identifier of the queue to be cleared. - -#### Example Request: - -``` -POST /queues/queue1/clear -``` - -#### Example Response: - -```json -{ - "id": "queue1", - "name": "Queue 1", - "status": "removed" -} -``` - -## WebSocket Endpoint - -Firebot hosts a local Websocket API that developers can use to get data from Firebot. - -- The API is hosted on port **7472**. All endpoints have the root **ws://localhost:7472/api/v1** -- All responses are in JSON. -- Don't forget that Firebot must be running for the API to be available. - -```json -{ - "type": "invoke", - "id": 0, - "name": "subscribe-events", - "data": [] -} -``` diff --git a/src/app/v5/dev/api/counters/page.mdx b/src/app/v5/dev/api/counters/page.mdx index c99f9b1..a886af2 100644 --- a/src/app/v5/dev/api/counters/page.mdx +++ b/src/app/v5/dev/api/counters/page.mdx @@ -1,93 +1,119 @@ -# Counters API - -## `GET /counters` - -#### Description: - -Fetches all available counters. - -#### Example Request: - -``` -GET /counters -``` +export const metadata = { + title: 'Counters', + description: 'Documentation for counter API endpoints.', +} -#### Example Response: +# Counters -```json -[ - { - "id": "counter1", - "name": "Counter 1", - "value": 10 - }, - { - "id": "counter2", - "name": "Counter 2", - "value": 15 - } -] -``` +The Counters API allows you to manage and retrieve counter values. --- -## `GET /counters/:counterId` - -#### Description: - -Fetches a specific counter by its `counterId`. - -#### Request Parameters: - -- `counterId`: The unique identifier of the counter. - -#### Example Request: - -``` -GET /counters/counter1 -``` - -#### Example Response: - -```json -{ - "id": "counter1", - "name": "Counter 1", - "value": 10 -} -``` +## List all counters {{ tag: 'GET', label: '/counters' }} + + + + Retrieves a list of all counters + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/counters + ``` + + + ```json {{ title: 'Response' }} + [ + { + "id": "counter1", + "name": "Counter 1", + "value": 10 + }, + { + "id": "counter2", + "name": "Counter 2", + "value": 15 + } + ] + ``` + + --- -## `POST /counters/:counterId` - -#### Description: - -Updates the value of an existing counter. Optionally, you can override the current value. - -#### Request Parameters: - -- `counterId`: The unique identifier of the counter to be updated. - -#### Request Body: +## Retrieve a counter {{ tag: 'GET', label: '/counters/:counterId' }} + + + + Fetches a specific counter by its `counterId`. + + ### URL Parameters + + + The unique identifier of the counter + + + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/counters/counter1 + ``` + + + ```json {{ title: 'Response' }} + { + "id": "counter1", + "name": "Counter 1", + "value": 10 + } + ``` + + -- `value`: The new value to set for the counter (required). -- `override`: A boolean indicating whether to override the counter's current value (optional, defaults to `false`). - -#### Example Request: - -```json -{ - "value": 20, - "override": true -} -``` - -#### Example Response: +--- -```json -{ - "oldValue": 10, - "newValue": 20 -} -``` +## Update a counter {{ tag: 'POST', label: '/counters/:counterId' }} + + + + Updates the value of an existing counter. Optionally, you can override the current value. + + ### Request Parameters + + + The unique identifier of the counter to be updated + + + + ### Request Body + + + The new value to set for the counter + + + A boolean indicating whether to override the counter's current value. + If false, the new value will be added to the current value (optional, defaults to `false`) + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST http://localhost:7472/api/v1/counters/counter1 \ + -H "Content-Type: application/json" \ + -d '{"value": 20, "override": true}' + ``` + + + ```json {{ title: 'Response' }} + { + "oldValue": 10, + "newValue": 20 + } + ``` + + diff --git a/src/app/v5/dev/api/currency/page.mdx b/src/app/v5/dev/api/currency/page.mdx index c34e5d0..b7944e9 100644 --- a/src/app/v5/dev/api/currency/page.mdx +++ b/src/app/v5/dev/api/currency/page.mdx @@ -1,153 +1,153 @@ -# Currency API - -## `GET /currencies/:currencyName?` - -#### Description: +export const metadata = { + title: 'Currency', + description: 'Documentation for currency API endpoints.', +} -Fetches currency data for a specific currency or all currencies if no currency name is provided. +# Currency -- If `currencyName` is specified, it will return data for the specified currency. -- If `currencyName` is not provided, it will return a list of all currencies. +The Currency API allows you to fetch currency data and top holders for a specific currency. -#### Example Request (for a specific currency): +--- -``` -GET /currencies/coin -``` +## List all currencies {{ tag: 'GET', label: '/currencies' }} + + + + Retrieves a list of all currencies + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/currencies + ``` + + + ```json {{ title: 'Response' }} + [ + { + "d073da00-a726-11e9-a874-7de9c8544807": { + "id": "d073da00-a726-11e9-a874-7de9c8544807", + "name": "coin", + "active": true, + "payout": 5, + "interval": 5, + "limit": 1000000, + "transfer": "Allow", + "bonus": {}, + "offline": 5, + } + }, + { + "d073da00-a726-11e9-a874-7de9c8544807": { + "id": "d073da00-a726-11e9-a874-7de9c8544807", + "name": "pups", + "active": true, + "payout": 5, + "interval": 5, + "limit": 1000000, + "transfer": "Allow", + "bonus": {}, + "offline": 5, + } + } + ] + ``` + + -#### Example Response (for a specific currency): +--- -```json -{ - "d073da00-a726-11e9-a874-7de9c8544807": { - "id": "d073da00-a726-11e9-a874-7de9c8544807", - "name": "coin", - "active": true, - "payout": 5, - "interval": 5, - "limit": 1000000, - "transfer": "Allow", - "bonus": {}, - "offline": 5, - "$$hashKey": "object:35427" - } -} -``` - -#### Example Request (for all currencies): - -``` -GET /currencies -``` - -#### Example Response (for all currencies): - -```json -[ - { - "d073da00-a726-11e9-a874-7de9c8544807": { - "id": "d073da00-a726-11e9-a874-7de9c8544807", - "name": "coin", - "active": true, - "payout": 5, - "interval": 5, - "limit": 1000000, - "transfer": "Allow", - "bonus": {}, - "offline": 5, - "$$hashKey": "object:35427" - } - }, - { - "d073da00-a726-11e9-a874-7de9c8544807": { - "id": "d073da00-a726-11e9-a874-7de9c8544807", - "name": "pups", - "active": true, - "payout": 5, - "interval": 5, - "limit": 1000000, - "transfer": "Allow", - "bonus": {}, - "offline": 5, - "$$hashKey": "object:35427" +## Retrieve a currency {{ tag: 'GET', label: '/currencies/:currencyName' }} + + + + Retrieves a specific currency + + ### URL Parameters + + + The name of the currency to retrieve + + + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/currencies/coin + ``` + + + ```json {{ title: 'Response' }} + { + "d073da00-a726-11e9-a874-7de9c8544807": { + "id": "d073da00-a726-11e9-a874-7de9c8544807", + "name": "coin", + "active": true, + "payout": 5, + "interval": 5, + "limit": 1000000, + "transfer": "Allow", + "bonus": {}, + "offline": 5, + } } - } -] -``` + ``` + + --- -## `GET /currencies/:currencyName/topHolders` - -#### Description: - -Fetches the top holders of a specific currency. By default, it will return the top 10 holders, but you can specify a -`count` query parameter to change the number of top holders returned. - -#### Request Parameters: - -- `currencyName`: The name of the currency (e.g., "coin", "pups"). -- `count`: (Optional) The number of top holders to return. If not specified, defaults to 10. - -#### Example Request (with `count` query parameter): - -``` -GET /currencies/pups/topHolders?count=2 -``` - -#### Example Response: - -```json -[ - { - "username": "fluffypanda", - "displayName": "FluffyPanda", - "currency": { - "d073da00-a726-11e9-a874-7de9c8544807": 281272, - "3eba5d80-4297-11ee-86eb-d7d7d2938882": 103665 - }, - "_id": "90448736" - }, - { - "username": "sparklenova", - "displayName": "SparkleNova", - "currency": { - "d073da00-a726-11e9-a874-7de9c8544807": 281272, - "3eba5d80-4297-11ee-86eb-d7d7d2938882": 103665 - }, - "_id": "90448726" - } -] -``` - -#### Example Request (default 10 top holders): - -``` -GET /currencies/coin/topHolders -``` - -#### Example Response (default top 10 holders): - -```json -[ - { - "username": "fluffypanda", - "displayName": "FluffyPanda", - "currency": { - "d073da00-a726-11e9-a874-7de9c8544807": 281272, - "3eba5d80-4297-11ee-86eb-d7d7d2938882": 103665 - }, - "_id": "90448736" - }, - { - "username": "sparklenova", - "displayName": "SparkleNova", - "currency": { - "d073da00-a726-11e9-a874-7de9c8544807": 281272, - "3eba5d80-4297-11ee-86eb-d7d7d2938882": 103665 - }, - "_id": "90448726" - } - // More users... -] -``` +## Retrieve top holders {{ tag: 'GET', label: '/currencies/:currencyName/topHolders' }} + + + + Retrieves the top holders of a specific currency + + ### URL Parameters + + + The name of the currency to retrieve top holders for + + + + ### Query Parameters + + + The number of top holders to return. Defaults to 10. + + + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/currencies/coin/topHolders + ``` + + + ```json {{ title: 'Response' }} + [ + { + "username": "fluffypanda", + "displayName": "FluffyPanda", + "currency": { + "d073da00-a726-11e9-a874-7de9c8544807": 281272, + "3eba5d80-4297-11ee-86eb-d7d7d2938882": 103665 + }, + "_id": "90448736" + }, + { + "username": "sparklenova", + "displayName": "SparkleNova", + "currency": { + "d073da00-a726-11e9-a874-7de9c8544807": 281272, + "3eba5d80-4297-11ee-86eb-d7d7d2938882": 103665 + }, + "_id": "90448726" + } + ] + ``` + + diff --git a/src/app/v5/dev/api/custom-roles/page.mdx b/src/app/v5/dev/api/custom-roles/page.mdx index 6beb596..16c1eb6 100644 --- a/src/app/v5/dev/api/custom-roles/page.mdx +++ b/src/app/v5/dev/api/custom-roles/page.mdx @@ -1,169 +1,226 @@ -# Custom Roles API - -## `GET /customRoles` - -#### Description: - -Fetches a list of all custom roles with the associated viewers. - -#### Example Response (JSON): - -```json -[ - { - "id": "role1", - "name": "Moderator", - "viewers": ["viewer1", "viewer2"] - }, - { - "id": "role2", - "name": "VIP", - "viewers": ["viewer3"] - } -] -``` - ---- - -## `GET /customRoles/:customRoleId` - -#### Description: - -Fetches a specific custom role by its ID. Returns role details and the list of viewers associated with it. - -#### Example Response (JSON): - -```json -{ - "id": "role1", - "name": "Moderator", - "viewers": ["viewer1", "viewer2"] +export const metadata = { + title: 'Custom Roles', + description: 'Documentation for custom roles API endpoints.', } -``` -#### Example Error Response (if the role does not exist): +# Custom Roles -```json -{ - "status": "error", - "message": "Custom role 'role1' not found" -} -``` +The Custom Roles API allows you to create, manage, and retrieve custom roles for viewers. --- -## `POST /customRoles/:customRoleId/viewer/:userId` - -#### Description: - -Adds a user to a custom role. You can specify the user by either `userId` or `username` via query parameter. - -#### Request Parameters: - -- `customRoleId`: The ID of the custom role to which the user is being added. -- `userId`: The ID of the viewer to be added to the role. - -#### Query Parameter: - -- `username`: Set to "true" if the user should be found by `username` instead of `userId`. - -#### Example Request (URL): - -``` -POST /customRoles/role1/viewer/viewer1?username=true -``` - -#### Example Success Response: - -```json -{ - "status": "success", - "message": "Viewer added to custom role" -} -``` - -#### Example Error Response (if user or custom role does not exist): - -```json -{ - "status": "error", - "message": "Specified viewer does not exist" -} -``` +## List all custom roles {{ tag: 'GET', label: '/customRoles' }} + + + + List all custom roles with associated viewers. + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/customRoles + ``` + + + ```json {{ title: 'Response' }} + [ + { + "id": "role1", + "name": "Moderator", + "viewers": ["viewer1", "viewer2"] + }, + { + "id": "role2", + "name": "VIP", + "viewers": ["viewer3"] + } + ] + ``` + + --- -### `DELETE /customRoles/:customRoleId/viewer/:userId` - -#### Description: - -Removes a user from a custom role. You can specify the user by either `userId` or `username` via query parameter. - -#### Request Parameters: - -- `customRoleId`: The ID of the custom role to which the user is being removed from. -- `userId`: The ID of the viewer to be removed from the role. - -#### Query Parameter: - -- `username`: Set to "true" if the user should be found by `username` instead of `userId`. - -#### Example Request (URL): - -``` -DELETE /customRoles/role1/viewer/viewer1?username=true -``` - -#### Example Success Response: - -```json -{ - "status": "success", - "message": "Viewer removed from custom role" -} -``` - -#### Example Error Response (if user or custom role does not exist): - -```json -{ - "status": "error", - "message": "Specified viewer does not exist" -} -``` +## Retrieve a custom role {{ tag: 'GET', label: '/customRoles/:customRoleId' }} + + + + Fetches a specific custom role by its ID. Returns role details and the list of viewers associated with it. + + ### URL Parameters + + + The ID of the custom role to retrieve. + + + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/customRoles/role1 + ``` + + + + ```json {{ title: 'Success' }} + { + "id": "role1", + "name": "Moderator", + "viewers": ["viewer1", "viewer2"] + } + ``` + ```json {{ title: 'Error' }} + { + "status": "error", + "message": "Custom role 'role1' not found" + } + ``` + + + + --- -### `DELETE /customRoles/:customRoleId/clear` - -#### Description: - -Removes all viewers from a custom role. - -#### Request Parameters: - -- `customRoleId`: The ID of the custom role from which all viewers are being removed. +## Add user to custom role {{ tag: 'POST', label: '/customRoles/:customRoleId/viewer/:userIdOrName' }} + + + + Adds a user to a custom role. + + ### URL Parameters + + + The ID of the custom role to which the user is being added. + + + The ID or username of the viewer to be added to the role. + + + + ### Query Parameters + + + Set to "true" if the user should be found by `username` instead of `userId`. + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST http://localhost:7472/api/v1/customRoles/role1/viewer/viewer1?username=true + ``` + + + + ```json {{ title: 'Success' }} + { + "status": "success", + "message": "Viewer added to custom role" + } + ``` + ```json {{ title: 'Error' }} + { + "status": "error", + "message": "Specified viewer does not exist" + } + ``` + + + + -#### Example Request (URL): - -``` -DELETE /customRoles/role1/clear -``` - -#### Example Success Response: +--- -```json -{ - "status": "success", - "message": "All viewers removed from the custom role" -} -``` +## Remove user from custom role {{ tag: 'DELETE', label: '/customRoles/:customRoleId/viewer/:userId' }} + + + + Removes a user from a custom role. You can specify the user by either `userId` or `username` via query parameter. + + ### URL Parameters + + + The ID of the custom role to which the user is being removed from. + + + The ID of the viewer to be removed from the role. + + + + ### Query Parameters + + + Set to "true" if the user should be found by `username` instead of `userId`. + + + + + + + ```bash {{ title: 'cURL' }} + curl -X DELETE http://localhost:7472/api/v1/customRoles/role1/viewer/viewer1?username=true + ``` + + + + ```json {{ title: 'Success' }} + { + "status": "success", + "message": "Viewer removed from custom role" + } + ``` + ```json {{ title: 'Error' }} + { + "status": "error", + "message": "Specified viewer does not exist" + } + ``` + + + + -#### Example Error Response (if custom role does not exist): +--- -```json -{ - "status": "error", - "message": "Specified custom role does not exist" -} -``` +## Remove all viewers from custom role {{ tag: 'DELETE', label: '/customRoles/:customRoleId/clear' }} + + + + Removes all viewers from a custom role. + + ### URL Parameters + + + The ID of the custom role from which all viewers are being removed. + + + + + + + ```bash {{ title: 'cURL' }} + curl -X DELETE http://localhost:7472/api/v1/customRoles/role1/clear + ``` + + + + ```json {{ title: 'Success' }} + { + "status": "success", + "message": "All viewers removed from the custom role" + } + ``` + ```json {{ title: 'Error' }} + { + "status": "error", + "message": "Specified custom role does not exist" + } + ``` + + + + \ No newline at end of file diff --git a/src/app/v5/dev/api/custom-variables/page.mdx b/src/app/v5/dev/api/custom-variables/page.mdx index a2b851a..6c77e1a 100644 --- a/src/app/v5/dev/api/custom-variables/page.mdx +++ b/src/app/v5/dev/api/custom-variables/page.mdx @@ -1,76 +1,126 @@ +export const metadata = { + title: 'Custom Variables', + description: 'Documentation for custom variable API endpoints.', +} + # Custom Variables -## `GET /custom-variables` +Custom Variables are created by the Custom Variable effect and can be used to store arbitrary data. + +--- + +## List all custom variables {{ tag: 'GET', label: '/custom-variables' }} + + + + Lists all custom variables in the system. + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/custom-variables + ``` + -#### Description: -Fetches all custom variables in the system. + ```json {{ title: 'Response' }} + [ + { + "name": "var1", + "data": "some data", + "ttl": 3600 + }, + { + "name": "var2", + "data": "more data", + "ttl": 0 + } + ] + ``` + + -#### Example Response (JSON): -```json -[ +--- + +## Retrieve a custom variable {{ tag: 'GET', label: '/custom-variables/:variableName' }} + + + + Fetches the value of a specific custom variable by its `variableName`. + + ### URL parameters + + + + The name of the custom variable to retrieve. + + + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/custom-variables/var1 + ``` + + + ```json {{ title: 'Response' }} { "name": "var1", "data": "some data", "ttl": 3600 - }, - { - "name": "var2", - "data": "more data", - "ttl": 0 } -] -``` + ``` + + -## `GET /custom-variables/:variableName` +--- -#### Description: -Fetches the value of a specific custom variable by its `variableName`. +## Set a custom variable {{ tag: 'POST', label: '/custom-variables/:variableName' }} -#### URL Parameters: -- `variableName` `string`: The name of the custom variable to retrieve. + + + Sets a custom variable by its `variableName` + + ### URL parameters -#### Example Request (URL): -``` -GET /custom-variables/var1 -``` + + + The name of the custom variable to set. + + -#### Example Response (JSON): -```json -{ - "name": "var1", - "data": "some data", - "ttl": 3600 -} -``` - -## `POST /custom-variables/:variableName` - -#### Description: -Sets a custom variable by its `variableName`. The request body should contain the data and optional TTL (time-to-live) -for the variable. + ### Request Body (JSON) -#### URL Parameters: -- `variableName` `string`: The name of the custom variable to set. + + + The new value for the variable. + + + Optional time-to-live for the variable in seconds. Set to 0 for no expiration. + + + -#### Request Body (JSON): -```json -{ - "data": "new value", - "ttl": 3600 -} -``` - -#### Example Response (Success): -```json -{ - "status": "success" -} -``` + + + ```bash {{ title: 'cURL' }} + curl -X POST http://localhost:7472/api/v1/custom-variables/var1 -d '{"data": "new value", "ttl": 3600}' + ``` + -#### Example Response (Error): -```json -{ - "status": "error", - "message": "No data provided" -} -``` \ No newline at end of file + + ```json {{ title: 'Success' }} + { + "status": "success" + } + ``` + ```json {{ title: 'Error' }} + { + "status": "error", + "message": "No data provided" + } + ``` + + + \ No newline at end of file diff --git a/src/app/v5/dev/api/effect-queues/page.mdx b/src/app/v5/dev/api/effect-queues/page.mdx index d5f11f2..ab2cf6e 100644 --- a/src/app/v5/dev/api/effect-queues/page.mdx +++ b/src/app/v5/dev/api/effect-queues/page.mdx @@ -1,170 +1,206 @@ -# Effect Queue API - -## `GET /queues` - -#### Description: - -Fetches all available effect queues. - -#### Example Request: - -``` -GET /queues -``` +export const metadata = { + title: 'Effect Queues', + description: 'Documentation for effect queue API endpoints.', +} -#### Example Response: +# Effect Queues -```json -[ - { - "id": "queue1", - "name": "Queue 1", - "status": "active" - }, - { - "id": "queue2", - "name": "Queue 2", - "status": "paused" - } -] -``` +The effect queues API allows you to manage effect queues in Firebot. --- -## `GET /queues/:queueId` - -#### Description: - -Fetches a specific effect queue by its `queueId`. - -#### Request Parameters: - -- `queueId`: The unique identifier of the queue. - -#### Example Request: - -``` -GET /queues/queue1 -``` - -#### Example Response: - -```json -{ - "id": "queue1", - "name": "Queue 1", - "status": "active" -} -``` +## List all effect queues {{ tag: 'GET', label: '/queues' }} + + + + Retrieves a list of all effect queues + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/queues + ``` + + + ```json {{ title: 'Response' }} + [ + { + "id": "queue1", + "name": "Queue 1", + "status": "active" + }, + { + "id": "queue2", + "name": "Queue 2", + "status": "paused" + } + ] + ``` + + --- -## `POST /queues/:queueId/pause` - -#### Description: - -Pauses the specified effect queue. - -#### Request Parameters: - -- `queueId`: The unique identifier of the queue to be paused. - -#### Example Request: - -``` -POST /queues/queue1/pause -``` - -#### Example Response: - -```json -{ - "id": "queue1", - "name": "Queue 1", - "status": "paused" -} -``` +## Retrieve an effect queue {{ tag: 'GET', label: '/queues/:queueId' }} + + + + Fetches a specific effect queue by its `queueId`. + + ### URL Parameters + + + The unique identifier of the queue + + + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/queues/queue1 + ``` + + + ```json {{ title: 'Response' }} + { + "id": "queue1", + "name": "Queue 1", + "status": "active" + } + ``` + + --- -## `POST /queues/:queueId/resume` - -#### Description: - -Resumes the specified effect queue. - -#### Request Parameters: - -- `queueId`: The unique identifier of the queue to be resumed. - -#### Example Request: - -``` -POST /queues/queue1/resume -``` - -#### Example Response: - -```json -{ - "id": "queue1", - "name": "Queue 1", - "status": "active" -} -``` +## Pause an effect queue {{ tag: 'POST', label: '/queues/:queueId/pause' }} + + + + Pauses the specified effect queue. + + ### URL Parameters + + + The unique identifier of the queue + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST http://localhost:7472/api/v1/queues/queue1/pause + ``` + + + ```json {{ title: 'Response' }} + { + "id": "queue1", + "name": "Queue 1", + "status": "paused" + } + ``` + + --- -## `POST /queues/:queueId/toggle` - -#### Description: - -Toggles the status of the specified effect queue (pauses if active, resumes if paused). - -#### Request Parameters: - -- `queueId`: The unique identifier of the queue to be toggled. - -#### Example Request: - -``` -POST /queues/queue1/toggle -``` - -#### Example Response: - -```json -{ - "id": "queue1", - "name": "Queue 1", - "status": "paused" -} -``` +## Resume an effect queue {{ tag: 'POST', label: '/queues/:queueId/resume' }} + + + + Resumes the specified effect queue. + + ### URL Parameters + + + The unique identifier of the queue + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST http://localhost:7472/api/v1/queues/queue1/resume + ``` + + + ```json {{ title: 'Response' }} + { + "id": "queue1", + "name": "Queue 1", + "status": "active" + } + ``` + + --- -## `POST /queues/:queueId/clear` - -#### Description: - -Clears the specified effect queue (removes the queue). +## Toggle an effect queue {{ tag: 'POST', label: '/queues/:queueId/toggle' }} + + + + Toggles the status of the specified effect queue (pauses if active, resumes if paused). + + ### URL Parameters + + + The unique identifier of the queue + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST http://localhost:7472/api/v1/queues/queue1/toggle + ``` + + + ```json {{ title: 'Response' }} + { + "id": "queue1", + "name": "Queue 1", + "status": "paused" + } + ``` + + -#### Request Parameters: - -- `queueId`: The unique identifier of the queue to be cleared. - -#### Example Request: - -``` -POST /queues/queue1/clear -``` - -#### Example Response: +--- -```json -{ - "id": "queue1", - "name": "Queue 1", - "status": "removed" -} -``` +## Clear an effect queue {{ tag: 'POST', label: '/queues/:queueId/clear' }} + + + + Clears the specified effect queue (removes the queue). + + ### URL Parameters + + + The unique identifier of the queue + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST http://localhost:7472/api/v1/queues/queue1/clear + ``` + + + ```json {{ title: 'Response' }} + { + "id": "queue1", + "name": "Queue 1", + "status": "removed" + } + ``` + + diff --git a/src/app/v5/dev/api/effects/page.mdx b/src/app/v5/dev/api/effects/page.mdx index c974637..ac4fbd0 100644 --- a/src/app/v5/dev/api/effects/page.mdx +++ b/src/app/v5/dev/api/effects/page.mdx @@ -1,10 +1,14 @@ export const metadata = { title: 'Effects', - description: 'This page documents the effects API endpoints.', + description: 'Documentation for effect API endpoints.', } # Effects +The effects API allows you to retrieve and trigger effects in Firebot. + +--- + ## List all effects {{ tag: 'GET', label: '/effects' }} diff --git a/src/app/v5/dev/api/endpoints/page.mdx b/src/app/v5/dev/api/endpoints/page.mdx deleted file mode 100644 index 02ceb85..0000000 --- a/src/app/v5/dev/api/endpoints/page.mdx +++ /dev/null @@ -1 +0,0 @@ -# Rest Endpoints diff --git a/src/app/v5/dev/api/oauth/page.mdx b/src/app/v5/dev/api/oauth/page.mdx index 79dfc63..4a03ce6 100644 --- a/src/app/v5/dev/api/oauth/page.mdx +++ b/src/app/v5/dev/api/oauth/page.mdx @@ -1,11 +1,15 @@ export const metadata = { - title: 'Authentication', + title: 'OAuth', description: - 'This page documents the oauth endpoints of the API.', + 'Documentation for oauth API endpoints.', } # OAuth +The OAuth API handles authentication with third-party providers like Twitch, Streamlabs, etc. + +--- + ## Trigger auth provider flow {{ tag: 'GET', label: '/auth' }} diff --git a/src/app/v5/dev/api/quotes/page.mdx b/src/app/v5/dev/api/quotes/page.mdx index 741544d..4303e3d 100644 --- a/src/app/v5/dev/api/quotes/page.mdx +++ b/src/app/v5/dev/api/quotes/page.mdx @@ -1,221 +1,283 @@ -# Quotes API - -## `GET /quotes` - -#### Description: - -Fetches all available quotes. - -#### Example Request: - -``` -GET /quotes -``` - -#### Example Response: - -```json -[ - { - "id": 1, - "text": "This is a sample quote.", - "originator": "John Doe", - "creator": "Jane Smith", - "game": "Game Name", - "createdAt": "2024-12-14T00:00:00Z" - }, - { - "id": 2, - "text": "Another quote here.", - "originator": "Alice", - "creator": "Bob", - "game": "Another Game", - "createdAt": "2024-12-13T00:00:00Z" - } -] -``` - ---- - -## `GET /quotes/:quoteId` - -#### Description: - -Fetches a specific quote by its `quoteId`. - -#### Request Parameters: - -- `quoteId`: The unique identifier of the quote. - -#### Example Request: - -``` -GET /quotes/1 -``` - -#### Example Response: - -```json -{ - "id": 1, - "text": "This is a sample quote.", - "originator": "John Doe", - "creator": "Jane Smith", - "game": "Game Name", - "createdAt": "2024-12-14T00:00:00Z" +export const metadata = { + title: 'Quotes', + description: 'Documentation for quote API endpoints.', } -``` ---- +# Quotes -## `POST /quotes` - -#### Description: - -Creates a new quote. - -#### Request Body: - -- `text`: The text content of the quote (required). -- `originator`: The person who originated the quote (required). -- `creator`: The creator of the quote (required). -- `game`: The game context (optional). - -#### Example Request: - -```json -{ - "text": "This is a new quote.", - "originator": "Alice", - "creator": "Bob", - "game": "Sample Game" -} -``` - -#### Example Response: - -```json -{ - "id": 3, - "text": "This is a new quote.", - "originator": "Alice", - "creator": "Bob", - "game": "Sample Game", - "createdAt": "2024-12-14T00:00:00Z" -} -``` +The Quotes API allows you to manage quotes in Firebot --- -### `PUT /quotes/:quoteId` - -#### Description: - -Creates or updates a specific quote. If a quote with the provided `quoteId` does not exist, it will be created; -otherwise, it will be updated. - -#### Request Parameters: - -- `quoteId`: The unique identifier of the quote to be updated or created. - -#### Request Body: - -- `text`: The text content of the quote (required). -- `originator`: The person who originated the quote (required). -- `creator`: The creator of the quote (required). -- `game`: The game context (optional). -- `createdAt`: The creation date (optional). - -#### Example Request: - -```json -{ - "text": "Updated quote content", - "originator": "Alice", - "creator": "Bob", - "game": "Sample Game", - "createdAt": "2024-12-14T00:00:00Z" -} -``` - -#### Example Response: - -```json -{ - "id": 1, - "text": "Updated quote content", - "originator": "Alice", - "creator": "Bob", - "game": "Sample Game", - "createdAt": "2024-12-14T00:00:00Z" -} -``` +## List all quotes {{ tag: 'GET', label: '/quotes' }} + + + + Retrieves a list of all quotes + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/quotes + ``` + + + ```json {{ title: 'Response' }} + [ + { + "id": 1, + "text": "This is a sample quote.", + "originator": "John Doe", + "creator": "Jane Smith", + "game": "Game Name", + "createdAt": "2024-12-14T00:00:00Z" + }, + { + "id": 2, + "text": "Another quote here.", + "originator": "Alice", + "creator": "Bob", + "game": "Another Game", + "createdAt": "2024-12-13T00:00:00Z" + } + ] + ``` + + --- -### `PATCH /quotes/:quoteId` - -#### Description: - -Partially updates an existing quote. You can update specific fields such as `text`, `originator`, `creator`, `game`, or -`createdAt`. - -#### Request Parameters: - -- `quoteId`: The unique identifier of the quote to be updated. - -#### Request Body: - -Any of the following fields can be included: - -- `text`: The text content of the quote. -- `originator`: The person who originated the quote. -- `creator`: The creator of the quote. -- `game`: The game context. -- `createdAt`: The creation date. - -#### Example Request: - -```json -{ - "text": "Partially updated quote content", - "originator": "Alice" -} -``` - -#### Example Response: - -```json -{ - "id": 1, - "text": "Partially updated quote content", - "originator": "Alice", - "creator": "Bob", - "game": "Sample Game", - "createdAt": "2024-12-14T00:00:00Z" -} -``` +## Retrieve a quote {{ tag: 'GET', label: '/quotes/:quoteId' }} + + + + Fetches a specific quote by its `quoteId`. + + ### URL Parameters + + + The unique identifier of the quote + + + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/quotes/1 + ``` + + + ```json {{ title: 'Response' }} + { + "id": 1, + "text": "This is a sample quote.", + "originator": "John Doe", + "creator": "Jane Smith", + "game": "Game Name", + "createdAt": "2024-12-14T00:00:00Z" + } + ``` + + --- -### `DELETE /quotes/:quoteId` +## Create a quote {{ tag: 'POST', label: '/quotes' }} + + + + Creates a new quote. + + ### Request Body + + + The text content of the quote + + + The person who originated the quote + + + The creator of the quote + + + The game context + + + + + + + ```json {{ title: 'Request Body' }} + { + "text": "This is a new quote.", + "originator": "Alice", + "creator": "Bob", + "game": "Sample Game" + } + ``` + + + ```json {{ title: 'Response' }} + { + "id": 3, + "text": "This is a new quote.", + "originator": "Alice", + "creator": "Bob", + "game": "Sample Game", + "createdAt": "2024-12-14T00:00:00Z" + } + ``` + + -#### Description: - -Deletes a specific quote by its `quoteId`. - -#### Request Parameters: +--- -- `quoteId`: The unique identifier of the quote to be deleted. +## Update a quote {{ tag: 'PUT', label: '/quotes/:quoteId' }} + + + + Creates or updates a specific quote. If a quote with the provided `quoteId` does not exist, it will be created; + otherwise, it will be updated. + + ### Request Parameters + + + The unique identifier of the quote to be updated or created + + + + ### Request Body + + + The text content of the quote + + + The person who originated the quote + + + The creator of the quote + + + The game context + + + The creation date + + + + + + + ```json {{ title: 'Request Body' }} + { + "text": "Updated quote content", + "originator": "Alice", + "creator": "Bob", + "game": "Sample Game", + "createdAt": "2024-12-14T00:00:00Z" + } + ``` + + + ```json {{ title: 'Response' }} + { + "id": 1, + "text": "Updated quote content", + "originator": "Alice", + "creator": "Bob", + "game": "Sample Game", + "createdAt": "2024-12-14T00:00:00Z" + } + ``` + + -#### Example Request: +--- -``` -DELETE /quotes/1 -``` +## Partially update a quote {{ tag: 'PATCH', label: '/quotes/:quoteId' }} + + + + Partially updates an existing quote. You can update specific fields such as `text`, `originator`, `creator`, `game`, + or `createdAt`. + + ### Request Parameters + + + The unique identifier of the quote to be updated + + + + ### Request Body + + + The text content of the quote + + + The person who originated the quote + + + The creator of the quote + + + The game context + + + The creation date + + + + + + + ```json {{ title: 'Request Body' }} + { + "text": "Partially updated quote content", + "originator": "Alice" + } + ``` + + + ```json {{ title: 'Response' }} + { + "id": 1, + "text": "Partially updated quote content", + "originator": "Alice", + "creator": "Bob", + "game": "Sample Game", + "createdAt": "2024-12-14T00:00:00Z" + } + ``` + + -#### Example Response: +--- -``` -HTTP Status 204 No Content -``` +## Delete a quote {{ tag: 'DELETE', label: '/quotes/:quoteId' }} + + + + Deletes a specific quote by its `quoteId`. + + ### Request Parameters + + + The unique identifier of the quote to be deleted + + + + + + + ```bash {{ title: 'cURL' }} + curl -X DELETE http://localhost:7472/api/v1/quotes/1 + ``` + + + ```html {{ title: 'Response' }} + HTTP Status 204 No Content + ``` + + \ No newline at end of file diff --git a/src/app/v5/dev/api/replace-variables/page.mdx b/src/app/v5/dev/api/replace-variables/page.mdx index ba15bb0..f824133 100644 --- a/src/app/v5/dev/api/replace-variables/page.mdx +++ b/src/app/v5/dev/api/replace-variables/page.mdx @@ -1,67 +1,84 @@ -# Variables +export const metadata = { + title: 'Replace Variables', + description: 'Documentation for replace variables API endpoints.', +} -## `GET /variables` +# Replace Variables -#### Description: +Replace Variables are used to retrieve data from Firebot in text fields and other places where you can use the $variableName syntax. -Fetches a list of all replace variables, sorted by their `handle` value. +--- -#### Example Response: +## List all replace variables {{ tag: 'GET', label: '/variables' }} -```json -[ - { - "definition": { - "handle": "example_variable_name", - "aliases": ["alias1", "alias2"], - "usage": "Example usage description", - "description": "Example variable definition description", - "examples": [ - { - "usage": "example usage 1", - "description": "Example description 1" + + + List all available replace variable definitions. + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/variables + ``` + + + ```json {{ title: 'Response' }} + [ + { + "definition": { + "handle": "example_variable_name", + "aliases": ["alias1", "alias2"], + "usage": "Example usage description", + "description": "Example variable definition description", + "examples": [ + { + "usage": "example usage 1", + "description": "Example description 1" + }, + { + "usage": "example usage 2", + "description": "Example description 2" + } + ], + "categories": [ + "common", + "trigger based", + "user based", + "text", + "numbers", + "advanced", + "obs", + "integrations" + ], + "triggers": { + "command": true, + "custom_script": true, + "startup_script": false, + "api": true, + "event": ["event1", "event2"], + "hotkey": false, + "timer": true, + "counter": false, + "preset": true, + "quick_action": false, + "manual": true + }, + "possibleDataOutput": [ + "null", + "bool", + "number", + "text", + "array", + "object", + "ALL" + ], + "hidden": false, + "spoof": true }, - { - "usage": "example usage 2", - "description": "Example description 2" - } - ], - "categories": [ - "common", - "trigger based", - "user based", - "text", - "numbers", - "advanced", - "obs", - "integrations" - ], - "triggers": { - "command": true, - "custom_script": true, - "startup_script": false, - "api": true, - "event": ["event1", "event2"], - "hotkey": false, - "timer": true, - "counter": false, - "preset": true, - "quick_action": false, - "manual": true - }, - "possibleDataOutput": [ - "null", - "bool", - "number", - "text", - "array", - "object", - "ALL" - ], - "hidden": false, - "spoof": true - }, - "handle": "ALL" - } -] -``` + "handle": "ALL" + } + ] + ``` + + diff --git a/src/app/v5/dev/api/status/page.mdx b/src/app/v5/dev/api/status/page.mdx index 41a5511..b54029c 100644 --- a/src/app/v5/dev/api/status/page.mdx +++ b/src/app/v5/dev/api/status/page.mdx @@ -1,17 +1,21 @@ export const metadata = { title: 'Status', description: - 'This page documents the status API endpoints.', + 'Documentation for the status API endpoint.', } # Status +The Status API allows you to check the current status of Firebot + +--- + ## Current status {{ tag: 'GET', label: '/status' }} - Fetches the current status of the application's connections, specifically the chat connection status. + Fetches the current status of Firebots connections, specifically the chat connection status. diff --git a/src/app/v5/dev/api/timers/page.mdx b/src/app/v5/dev/api/timers/page.mdx index 046c0e3..8ffca54 100644 --- a/src/app/v5/dev/api/timers/page.mdx +++ b/src/app/v5/dev/api/timers/page.mdx @@ -1,105 +1,191 @@ -# Timers API - -## `GET /timers` - -#### Description: - -Fetches all available timers. - -#### Example Request: - -``` -GET /timers -``` +export const metadata = { + title: 'Timers', + description: + 'Documentation for the timer API endpoints.', +} -#### Example Response: +# Timers -```json -[ - { - "id": "timer1", - "name": "Timer 1", - "active": true - }, - { - "id": "timer2", - "name": "Timer 2", - "active": false - } -] -``` +The timers API allows you to manage timers in Firebot. --- -## `GET /timers/:timerId` - -#### Description: - -Fetches a specific timer by its `timerId`. - -#### Request Parameters: - -- `timerId`: The unique identifier of the timer. - -#### Example Request: - -``` -GET /timers/timer1 -``` - -#### Example Response: - -```json -{ - "id": "timer1", - "name": "Timer 1", - "active": true -} -``` +## List all timers {{ tag: 'GET', label: '/timers' }} + + + + Retrieves a list of all timers + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/timers + ``` + + + ```json {{ title: 'Response' }} + [ + { + "id": "timer1", + "name": "Timer 1", + "active": true + }, + { + "id": "timer2", + "name": "Timer 2", + "active": false + } + ] + ``` + + --- -## `POST /timers/:timerId/:action` - -#### Description: - -Performs an action on the specified timer. - -#### Request Parameters: - -- `timerId`: The unique identifier of the timer to be modified. -- `action`: The action to perform on the timer. Can be one of the following: -- `enable`: Enables the timer. -- `disable`: Disables the timer. -- `toggle`: Toggles the active state of the timer. -- `clear`: Clears the timer's interval. +## Retrieve a timer {{ tag: 'GET', label: '/timers/:timerId' }} + + + + Fetches a specific timer by its `timerId`. + + ### URL Parameters + + + The unique identifier of the timer + + + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/timers/timer1 + ``` + + + ```json {{ title: 'Response' }} + { + "id": "timer1", + "name": "Timer 1", + "active": true + } + ``` + + -#### Example Request: +--- -``` -POST /timers/timer1/enable -``` +## Enable a timer {{ tag: 'POST', label: '/timers/:timerId/enable' }} + + + + Enables a timer. + + ### URL Parameters + + + The unique identifier of the timer to enable + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST http://localhost:7472/api/v1/timers/timer1/enable + ``` + + + ```html {{ title: 'Response' }} + HTTP Status 200 No Content + ``` + + -#### Example Response: +--- -```json -{ - "status": "success", - "message": "Timer enabled" -} -``` +## Disable a timer {{ tag: 'POST', label: '/timers/:timerId/disable' }} + + + + Disables a timer. + + ### URL Parameters + + + The unique identifier of the timer to disable + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST http://localhost:7472/api/v1/timers/timer1/disable + ``` + + + ```html {{ title: 'Response' }} + HTTP Status 200 No Content + ``` + + -#### Example Request: +--- -``` -POST /timers/timer1/clear -``` +## Toggle a timer {{ tag: 'POST', label: '/timers/:timerId/toggle' }} + + + + Toggles the active state of a timer. + + ### URL Parameters + + + The unique identifier of the timer to toggle + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST http://localhost:7472/api/v1/timers/timer1/toggle + ``` + + + ```html {{ title: 'Response' }} + HTTP Status 200 No Content + ``` + + -#### Example Response: +--- -```json -{ - "status": "success", - "message": "Timer interval cleared" -} -``` +## Clear a timer {{ tag: 'POST', label: '/timers/:timerId/clear' }} + + + + Clears a timer's interval. + + ### URL Parameters + + + The unique identifier of the timer to clear + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST http://localhost:7472/api/v1/timers/timer1/clear + ``` + + + ```html {{ title: 'Response' }} + HTTP Status 200 No Content + ``` + + \ No newline at end of file diff --git a/src/app/v5/dev/api/viewers/page.mdx b/src/app/v5/dev/api/viewers/page.mdx index 0aca8ec..25aedd6 100644 --- a/src/app/v5/dev/api/viewers/page.mdx +++ b/src/app/v5/dev/api/viewers/page.mdx @@ -1,64 +1,238 @@ -# Viewers +export const metadata = { + title: 'Viewers', + description: 'Documentation for viewer API endpoints.', +} -## **GET** `/viewers` +# Viewers -#### Description: +The Viewers API provides endpoints for managing viewer metadata, currency, and custom roles. -Retrieves a list of all users with their usernames and IDs. +--- -#### Example Response: +## List all viewers {{ tag: 'GET', label: '/viewers' }} + + + + Retrieves a list of all users with their usernames and IDs. + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/viewers + ``` + + + ```json {{ title: 'Response' }} + [ + { + "id": "1000638563", + "username": "ebiggz", + "displayName": "ebiggz" + }, + { + "id": "1000678901", + "username": "johnsmith92", + "displayName": "johnsmith92" + } + ] + ``` + + -Retrieves a list of all users with their usernames and IDs. +--- -```json -[ - { - "id": "1000638563", - "username": "ebiggz", - "displayName": "ebiggz" - }, - { - "id": "1000678901", - "username": "johnsmith92", - "displayName": "johnsmith92" - } -] -``` +## Export all viewers {{ tag: 'GET', label: '/viewers/export' }} + + + + Exports all user data as JSON, including expanded user currency information. + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/viewers/export + ``` + + + ```json {{ title: 'Response' }} + [ + { + "id": "1000638593", + "username": "ebiggz", + "displayName": "ebiggz", + "currency": { + "d073da00-a726-11e9-a874-7de9c8544807": { + "id": "d073da00-a726-11e9-a874-7de9c8544807", + "name": "points", + "amount": 150 + }, + "3eba5d80-4297-11ee-86eb-d7d7d2938882": { + "id": "3eba5d80-4297-11ee-86eb-d7d7d2938882", + "name": "coins", + "amount": 130 + } + } + }, + { + "id": "1000678901", + "username": "johnsmith92", + "displayName": "johnsmith92", + "currency": { + "d073da00-a726-11e9-a874-7de9c8544807": { + "id": "d073da00-a726-11e9-a874-7de9c8544807", + "name": "points", + "amount": 150 + }, + "3eba5d80-4297-11ee-86eb-d7d7d2938882": { + "id": "3eba5d80-4297-11ee-86eb-d7d7d2938882", + "name": "coins", + "amount": 130 + } + } + } + ] + ``` + + --- -## **GET** `/viewers/export` +## Retrieve a viewer {{ tag: 'GET', label: '/viewers/:userIdOrName' }} + + + + Retrieves metadata for a specific user based on `userId` (or `username` if specified). + + ### URL Parameters + + + The user ID or username of the viewer to retrieve. + + + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/viewers/1000638593 + ``` + + + ```json {{ title: 'Response' }} + { + "id": "1000638593", + "username": "sapherydesing", + "displayName": "sapherydesing", + "customRoles": ["coolPeople", "partyPeople"] + } + ``` + + -#### Description: +--- -Exports all user data as JSON, including expanded user currency information. +## Update viewer metadata {{ tag: 'POST', label: '/viewers/:userId/metadata/:metadataKey' }} + + + + Updates the value of a metadata key for a specific user. + + ### URL Parameters + + + The user ID of the viewer to update. + + + The metadata key to update. + + + + ### Body Parameters + + + The new value for the metadata key. + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST http://localhost:7472/api/v1/viewers/1000638593/metadata/someKey -d '{"data": "someValue"}' + ``` + + + ```json {{ title: 'Response' }} + { + "status": "success", + "message": "Metadata updated successfully" + } + ``` + + -#### Example Response: +--- -```json -[ - { - "id": "1000638593", - "username": "ebiggz", - "displayName": "ebiggz", - "currency": { - "d073da00-a726-11e9-a874-7de9c8544807": { - "id": "d073da00-a726-11e9-a874-7de9c8544807", - "name": "points", - "amount": 150 - }, - "3eba5d80-4297-11ee-86eb-d7d7d2938882": { - "id": "3eba5d80-4297-11ee-86eb-d7d7d2938882", - "name": "coins", - "amount": 130 - } +## Delete viewer metadata {{ tag: 'DELETE', label: '/viewers/:userId/metadata/:metadataKey' }} + + + + Removes a metadata key for a specific user. + + ### URL Parameters + + + The user ID of the viewer to update. + + + The metadata key to remove. + + + + + + + ```bash {{ title: 'cURL' }} + curl -X DELETE http://localhost:7472/api/v1/viewers/1000638593/metadata/someKey + ``` + + + ```json {{ title: 'Response' }} + { + "status": "success", + "message": "Metadata key removed successfully" } - }, - { - "id": "1000678901", - "username": "johnsmith92", - "displayName": "johnsmith92", - "currency": { + ``` + + + +--- + +## Retrieve viewer currencies {{ tag: 'GET', label: '/viewers/:userId/currency' }} + + + + Retrieves the list of currencies associated with a specific user. + + ### URL Parameters + + + The user ID of the viewer to retrieve currency for. + + + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/viewers/1000638593/currency + ``` + + + ```json {{ title: 'Response' }} + { "d073da00-a726-11e9-a874-7de9c8544807": { "id": "d073da00-a726-11e9-a874-7de9c8544807", "name": "points", @@ -70,169 +244,183 @@ Exports all user data as JSON, including expanded user currency information. "amount": 130 } } - } -] -``` - ---- - -## **GET** `/viewers/:userId` - -#### Description: - -Retrieves metadata for a specific user based on `userId` (or `username` if specified). - -#### Example Response: - -```json -{ - "id": "1000638593", - "username": "sapherydesing", - "displayName": "sapherydesing", - "customRoles": ["coolPeople", "partyPeople"] -} -``` + ``` + + --- -## **POST** `/viewers/:userId/metadata/:metadataKey` - -## **PUT** `/viewers/:userId/metadata/:metadataKey` - -#### Description: - -Updates the value of a metadata key for a specific user. - -#### Example Response: - -```json -{ - "status": "success", - "message": "Metadata updated successfully" -} -``` - ---- - -## **DELETE** `/viewers/:userId/metadata/:metadataKey` - -#### Description: - -Removes a metadata key for a specific user. - -#### Example Response: - -```json -{ - "status": "success", - "message": "Metadata key removed successfully" -} -``` - ---- - -## **GET** `/viewers/:userId/currency` - -#### Description: - -Retrieves the list of currencies associated with a specific user. - -#### Example Response: - -```json -{ - "d073da00-a726-11e9-a874-7de9c8544807": { - "id": "d073da00-a726-11e9-a874-7de9c8544807", - "name": "points", - "amount": 150 - }, - "3eba5d80-4297-11ee-86eb-d7d7d2938882": { - "id": "3eba5d80-4297-11ee-86eb-d7d7d2938882", - "name": "coins", - "amount": 130 - } -} -``` - ---- - -## **GET** `/viewers/:userId/currency/:currencyId` - -#### Description: - -Retrieves details for a specific currency associated with a user. - -#### Example Response: - -```json -{ - "id": "d073da00-a726-11e9-a874-7de9c8544807", - "name": "points", - "amount": 150 -} -``` +## Retrieve viewer currency {{ tag: 'GET', label: '/viewers/:userId/currency/:currencyId' }} + + + + Retrieves details for a specific currency associated with a user. + + ### URL Parameters + + + The user ID of the viewer to retrieve currency for. + + + The currency ID to retrieve. + + + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/viewers/1000638593/currency/d073da00-a726-11e9-a874-7de9c8544807 + ``` + + + ```json {{ title: 'Response' }} + { + "id": "d073da00-a726-11e9-a874-7de9c8544807", + "name": "points", + "amount": 150 + } + ``` + + --- -## **POST** `/viewers/:userId/currency/:currencyId` - -#### Description: - -Adjusts the amount of a specific currency for the user. - -#### Example Response: - -```json -{ - "status": "success", - "message": "Currency updated successfully" -} -``` +## Update viewer currency {{ tag: 'POST', label: '/viewers/:userId/currency/:currencyId' }} + + + + Adjusts the amount of a specific currency for the user. + + ### URL Parameters + + + The user ID of the viewer to update currency for. + + + The currency ID to update. + + + + ### Body Parameters + + + The new amount for the currency. + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST http://localhost:7472/api/v1/viewers/1000638593/currency/d073da00-a726-11e9-a874-7de9c8544807 -d '{"amount": 200}' + ``` + + + ```json {{ title: 'Response' }} + { + "status": "success", + "message": "Currency updated successfully" + } + ``` + + --- -## **GET** `/viewers/:userId/customRoles` - -#### Description: - -Retrieves a list of custom roles associated with a specific user. - -#### Example Response: - -```json -["coolPeople", "partyPeople"] -``` +## Retrieve viewer custom roles {{ tag: 'GET', label: '/viewers/:userId/customRoles' }} + + + + Retrieves a list of custom roles associated with a specific user. + + ### URL Parameters + + + The user ID of the viewer to retrieve custom roles for. + + + + + + + ```bash {{ title: 'cURL' }} + curl http://localhost:7472/api/v1/viewers/1000638593/customRoles + ``` + + + ```json {{ title: 'Response' }} + ["coolPeople", "partyPeople"] + ``` + + --- -## **POST** `/viewers/:userId/customRoles/:customRoleId` - -#### Description: - -Adds a user to a custom role. - -#### Example Response (JSON): - -```json -{ - "status": "success", - "message": "User added to custom role" -} -``` +## Add viewer to custom role {{ tag: 'POST', label: '/viewers/:userId/customRoles/:customRoleId' }} + + + + Adds a user to a custom role. + + ### URL Parameters + + + The user ID of the viewer to add to the custom role. + + + The ID of the custom role to add the user to. + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST http://localhost:7472/api/v1/viewers/1000638593/customRoles/coolPeople + ``` + + + ```json {{ title: 'Response' }} + { + "status": "success", + "message": "User added to custom role" + } + ``` + + --- -## **DELETE** `/viewers/:userId/customRoles/:customRoleId` - -#### Description: - -Removes a user from a custom role. - -#### Example Response: - -```json -{ - "status": "success", - "message": "User removed from custom role" -} -``` +## Remove viewer from custom role {{ tag: 'DELETE', label: '/viewers/:userId/customRoles/:customRoleId' }} + + + + Removes a user from a custom role. + + ### URL Parameters + + + The user ID of the viewer to remove from the custom role. + + + The ID of the custom role to remove the user from. + + + + + + + ```bash {{ title: 'cURL' }} + curl -X DELETE http://localhost:7472/api/v1/viewers/1000638593/customRoles/coolPeople + ``` + + + ```json {{ title: 'Response' }} + { + "status": "success", + "message": "User removed from custom role" + } + ``` + +