FirebotDocs
Follow us on GitHubJoin our Discord server

Viewers

The Viewers API provides endpoints for managing viewer metadata, currency, and custom roles.

GET/viewers

List all viewers

Retrieves a list of all users with their usernames and IDs.

Request

GET
/viewers
curl http://localhost:7472/api/v1/viewers

Response

[
  {
    "id": "1000638563",
    "username": "ebiggz",
    "displayName": "ebiggz"
  },
  {
    "id": "1000678901",
    "username": "johnsmith92",
    "displayName": "johnsmith92"
  }
]
GET/viewers/export

Export all viewers

Exports all user data as JSON, including expanded user currency information.

Request

GET
/viewers/export
curl http://localhost:7472/api/v1/viewers/export

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/:userIdOrName

Retrieve a viewer

Retrieves metadata for a specific user based on userId (or username if specified).

URL Parameters

  • Name
    userIdOrName
    Type
    string
    Description

    The user ID or username of the viewer to retrieve.

Request

GET
/viewers/:userIdOrName
curl http://localhost:7472/api/v1/viewers/1000638593

Response

{
  "id": "1000638593",
  "username": "sapherydesing",
  "displayName": "sapherydesing",
  "customRoles": ["coolPeople", "partyPeople"]
}
POST/viewers/:userId/metadata/:metadataKey

Update viewer metadata

Updates the value of a metadata key for a specific user.

URL Parameters

  • Name
    userId
    Type
    string
    Description

    The user ID of the viewer to update.

  • Name
    metadataKey
    Type
    string
    Description

    The metadata key to update.

Body Parameters

  • Name
    data
    Type
    string
    Description

    The new value for the metadata key.

Request

POST
/viewers/:userId/metadata/:metadataKey
curl -X POST http://localhost:7472/api/v1/viewers/1000638593/metadata/someKey -d '{"data": "someValue"}'

Response

{
  "status": "success",
  "message": "Metadata updated successfully"
}
DELETE/viewers/:userId/metadata/:metadataKey

Delete viewer metadata

Removes a metadata key for a specific user.

URL Parameters

  • Name
    userId
    Type
    string
    Description

    The user ID of the viewer to update.

  • Name
    metadataKey
    Type
    string
    Description

    The metadata key to remove.

Request

DELETE
/viewers/:userId/metadata/:metadataKey
curl -X DELETE http://localhost:7472/api/v1/viewers/1000638593/metadata/someKey

Response

{
  "status": "success",
  "message": "Metadata key removed successfully"
}
GET/viewers/:userId/currency

Retrieve viewer currencies

Retrieves the list of currencies associated with a specific user.

URL Parameters

  • Name
    userId
    Type
    string
    Description

    The user ID of the viewer to retrieve currency for.

Request

GET
/viewers/:userId/currency
curl http://localhost:7472/api/v1/viewers/1000638593/currency

Response

{
  "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

Retrieve viewer currency

Retrieves details for a specific currency associated with a user.

URL Parameters

  • Name
    userId
    Type
    string
    Description

    The user ID of the viewer to retrieve currency for.

  • Name
    currencyId
    Type
    string
    Description

    The currency ID to retrieve.

Request

GET
/viewers/:userId/currency/:currencyId
curl http://localhost:7472/api/v1/viewers/1000638593/currency/d073da00-a726-11e9-a874-7de9c8544807

Response

{
  "id": "d073da00-a726-11e9-a874-7de9c8544807",
  "name": "points",
  "amount": 150
}
POST/viewers/:userId/currency/:currencyId

Update viewer currency

Adjusts the amount of a specific currency for the user.

URL Parameters

  • Name
    userId
    Type
    string
    Description

    The user ID of the viewer to update currency for.

  • Name
    currencyId
    Type
    string
    Description

    The currency ID to update.

Body Parameters

  • Name
    amount
    Type
    number
    Description

    The new amount for the currency.

Request

POST
/viewers/:userId/currency/:currencyId
curl -X POST http://localhost:7472/api/v1/viewers/1000638593/currency/d073da00-a726-11e9-a874-7de9c8544807 -d '{"amount": 200}'

Response

{
  "status": "success",
  "message": "Currency updated successfully"
}
GET/viewers/:userId/customRoles

Retrieve viewer custom roles

Retrieves a list of custom roles associated with a specific user.

URL Parameters

  • Name
    userId
    Type
    string
    Description

    The user ID of the viewer to retrieve custom roles for.

Request

GET
/viewers/:userId/customRoles
curl http://localhost:7472/api/v1/viewers/1000638593/customRoles

Response

["coolPeople", "partyPeople"]
POST/viewers/:userId/customRoles/:customRoleId

Add viewer to custom role

Adds a user to a custom role.

URL Parameters

  • Name
    userId
    Type
    string
    Description

    The user ID of the viewer to add to the custom role.

  • Name
    customRoleId
    Type
    string
    Description

    The ID of the custom role to add the user to.

Request

POST
/viewers/:userId/customRoles/:customRoleId
curl -X POST http://localhost:7472/api/v1/viewers/1000638593/customRoles/coolPeople

Response

{
  "status": "success",
  "message": "User added to custom role"
}
DELETE/viewers/:userId/customRoles/:customRoleId

Remove viewer from custom role

Removes a user from a custom role.

URL Parameters

  • Name
    userId
    Type
    string
    Description

    The user ID of the viewer to remove from the custom role.

  • Name
    customRoleId
    Type
    string
    Description

    The ID of the custom role to remove the user from.

Request

DELETE
/viewers/:userId/customRoles/:customRoleId
curl -X DELETE http://localhost:7472/api/v1/viewers/1000638593/customRoles/coolPeople

Response

{
  "status": "success",
  "message": "User removed from custom role"
}