v1 Endpoints

Twitch Events

The twitch events endpoint allows you to query the twitch events stored in the database, as well as the ability to trigger test events.

GET `/api/v1/twitch-events`

Get a list of the most recent events that have been received. This endpoint is paginated, meaning that you may need to make multiple requests to get the data that you want. To know the URLs for pagination, see the next and previous fields in.

Request

curl http://<TAU_SERVER>/api/v1/twitch-events -H 'Authorization: Token <AUTH_TOKEN>'

Response

{
    "next": "http://localhost:8000/api/v1/twitch-events?cursor=cD0yMDIxLTA2LTI1KzA0JTNBMDclM0ExMS4zMTczOTclMkIwMCUzQTAw",
    "previous": null,
    "results": [
        {
            "id": "cd1d8698-7d36-4a0e-9f60-e796b2cf277f",
            "event_id": "ln5OqB4kadShCJmzcwNq9qUxhJMMnZEhm3jMRW77vL8=",
            "event_type": "stream-offline",
            "event_source": "EventSub",
            "event_data": {
                "broadcaster_user_id": "501585826",
                "broadcaster_user_name": "4DavidBlue",
                "broadcaster_user_login": "4davidblue"
            },
            "created": "2021-06-26T05:42:29+0000",
            "origin": "twitch"
        },
        ...
      }
    ]
}

Filters are also supported by the twitch events endpoint in order to limit results. Supported filters:

Event Type (event_type)
User ID (user_id)
Username (user_name)
Reward ID (reward_id)
Raid From User Name (raid_from)
Raid To User Name (raid_to)

Filters can be specified using query parameters, and multiple filters can be specified, for example to get all raid events from BaldBeardedBuilder:

Request

curl http://<TAU_SERVER>/api/v1/twitch-events?event_type=raid&user_name=baldbeardedbuilder -H 'Authorization: Token <AUTH_TOKEN>'

or use the raid_from filter without specifying the raid event type:

curl http://<TAU_SERVER>/api/v1/twitch-events?raid_from=baldbeardedbuilder -H 'Authorization: Token <AUTH_TOKEN>'

POST `/api/v1/twitch-events`

Leveraging POST requests you are able to add entries to the database. Note this endpoint will make the event origin appear as coming from twitch.

Request

curl --request POST http://<TAU_SERVER>/api/v1/twitch-events -H 'Authorization: Token <AUTH_TOKEN>' -H 'Content-type: application/json' --data '{"event_type":"stream-offline","event_source":"EventSub","event_data":{"broadcaster_user_id":"536397236","broadcaster_user_name":"FiniteSingularity","broadcaster_user_login":"finitesingularity"}}'

Response:

{
  "id": "d760ecf6-266d-4e7d-9c18-05fe6ce07abf",
  "event_id": null,
  "event_type": "stream-offline",
  "event_source": "EventSub",
  "event_data": {
    "broadcaster_user_id": "536397236",
    "broadcaster_user_name": "FiniteSingularity",
    "broadcaster_user_login": "finitesingularity"
  },
  "created": "2021-06-26T18:47:36+0000",
  "origin": "twitch"
}

POST `/api/v1/twitch-events/<EVENT_TYPE>/test`

Use this endpoint to create test entries that are sent to your application and stored in the database.

Request

curl --request POST http://<TAU_SERVER>/api/v1/twitch-events/stream-offline/test -H 'Authorization: Token <AUTH_TOKEN>' -H 'Content-type: application/json'  --data '{"broadcaster_user_id":"536397236","broadcaster_user_name":"FiniteSingularity","broadcaster_user_login":"finitesingularity"}'

Response

{
  "id": null,
  "event_id": "0c22e9ab-0c13-44e8-9ce1-c4f5cab11d51",
  "event_type": "stream-offline",
  "event_source": "TestCall",
  "event_data": {
    "broadcaster_user_id": "536397236",
    "broadcaster_user_name": "FiniteSingularity",
    "broadcaster_user_login": "finitesingularity"
  },
  "created": "2021-06-27T17:39:19.753994+00:00",
  "origin": "test"
}

Heartbeats

The heartbeat endpoint allows you to perform a health check on the server application. It does not require authentication/authorization, and on success will return an http 200 with the message outlined below.

GET `/api/v1/heartbeat`

Request

curl http://<TAU_SERVER>/api/v1/heartbeat

Response

{
  "message": "pong"
}

Streamers

The streamers API lists all the streamers that you are monitoring for notifications when they go online/offline. You can also get a list of their streams on a nested endpoint.

GET `/api/v1/streamers`

Get the list of streamers TAU is monitoring for online/offline notifications

Request

curl http:<TAU_SERVER>/api/v1/streamers -H 'Authorization: Token <AUTH_TOKEN>'

Response

[
  {
    "id": "e61a6604-9757-4b89-9f0d-4b9b446e95f8",
    "twitch_username": "FiniteSingularity",
    "twitch_id": "536397236",
    "streaming": false,
    "disabled": false,
    "created": "2021-06-24T04:13:40+0000",
    "updated": "2021-06-26T06:52:49+0000"
  }
]

POST `/api/v1/streamers`

Add a streamer to monitor for online/offline notifications

Request

curl --request POST http://<TAU_SERVER>/api/v1/streamers  -H 'Authorization: Token <AUTH_TOKEN>' -H 'Content-type: application/json' --data '{"twitch_username":"TwitchDev","streaming":false,"disabled":false}'

Response

{
  "id": "1e10ea57-4c7d-475c-9d09-b15083b7cc79",
  "twitch_username": "TwitchDev",
  "twitch_id": "141981764",
  "streaming": false,
  "disabled": false,
  "created": "2021-06-27T01:23:17+0000",
  "updated": "2021-06-27T01:23:17+0000"
}

GET `/api/v1/streamers/<ID>`

Get the details for a specific streamer

Request

curl http:<TAU_SERVER>/api/v1/streamers/<ID> -H 'Authorization: Token <AUTH_TOKEN>'

Response

{
  "id": "e61a6604-9757-4b89-9f0d-4b9b446e95f8",
  "twitch_username": "FiniteSingularity",
  "twitch_id": "536397236",
  "streaming": false,
  "disabled": false,
  "created": "2021-06-24T04:13:40+0000",
  "updated": "2021-06-26T06:52:49+0000"
}

GET `/api/v1/streamers/<ID>/streams`

Get a list of streams for a specific streamer

Request

curl http:<TAU_SERVER>/api/v1/streamers/<ID>/streams -H 'Authorization: Token <AUTH_TOKEN>'

Response

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "36071e1c-bccd-46f6-bae7-5662f748dece",
      "stream_id": "42566059805",
      "user_id": "501585826",
      "user_login": "4davidblue",
      "user_name": "4davidblue",
      "game_id": "509658",
      "game_name": "Just Chatting",
      "type": "live",
      "title": "CELEBRITY GUEST 🡆 !guest !wp !gif !donate !freesub",
      "viewer_count": 0,
      "started_at": "2021-06-26T23:51:07+0000",
      "ended_at": null,
      "language": "en",
      "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_4davidblue-{width}x{height}.jpg",
      "tag_ids": null,
      "is_mature": false
    },
    ...
  ]
}

GET `/api/v1/streamers/<ID>/streams/latest`

Gets the latest stream for a specific streamer

Request

curl http:<TAU_SERVER>/api/v1/streamers/<ID>/streams/latest -H 'Authorization: Token <AUTH_TOKEN>'

Response

{
  "id": "36071e1c-bccd-46f6-bae7-5662f748dece",
  "stream_id": "42566059805",
  "user_id": "501585826",
  "user_login": "4davidblue",
  "user_name": "4davidblue",
  "game_id": "509658",
  "game_name": "Just Chatting",
  "type": "live",
  "title": "CELEBRITY GUEST 🡆 !guest !wp !gif !donate !freesub",
  "viewer_count": 0,
  "started_at": "2021-06-26T23:51:07+0000",
  "ended_at": null,
  "language": "en",
  "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_4davidblue-{width}x{height}.jpg",
  "tag_ids": null,
  "is_mature": false
}

Twitch Scopes

Lists the available twitch scopes and if they are required or not

GET `/api/v1/twitch/scopes`

Request

curl http://<TAU_SERVER>/api/v1/twitch/scopes -H 'Authorization: Token <AUTH_TOKEN>'

Response

[
  {
    "id": "a2da0132-760a-4776-8c2d-827ce177d07f",
    "scope": "analytics:read:extensions",
    "required": false
  },
  {
    "id": "65c285f5-4b6e-4a3d-9e72-b562b94a7785",
    "scope": "analytics:read:games",
    "required": false
  },
  ...
]

POST `/api/v1/twitch/scopes`

Create a new scope, be careful you probably don't want to do this, if you add a duplicate it will mess up the UI.

Request

curl --request POST http://<TAU_SERVER>/api/v1/twitch/scopes/  -H 'Authorization: Token <AUTH_TOKEN>' -H 'Content-type: application/json' --data '{"scope":"user:read:subscriptions","required":false}'

Response

{
  "id": "11585ceb-cae2-4c3a-b6ff-60e774632fc2",
  "scope": "user:read:subscriptions",
  "required": false
}

GET `/api/v1/twitch/scopes/<ID>`

Get information on a specific twitch scope by ID

Request

curl http://<TAU_SERVER>/api/v1/twitch/scopes/<ID> -H 'Authorization: Token <AUTH_TOKEN>'

Response

{
  "id": "524836e3-71b3-4521-8b07-e7d44d754926",
  "scope": "user:read:subscriptions",
  "required": false
}

Helix Endpoints

A breakdown of helix endpoints, what HTTP method they use, and what scope they require

GET `/api/v1/twitch/helix-endpoints`

Gets data on all the helix endpoints

Request

curl http://<TAU_SERVER>/api/v1/twitch/helix-endpoints -H 'Authorization: Token <AUTH_TOKEN>'

Response

[
  {
    "id": "3e2dc3a8-3faa-4fd8-9c96-b6f1a86c846c",
    "description": "Start Commercial",
    "endpoint": "channels/commercial",
    "method": "POST",
    "reference_url": "https://dev.twitch.tv/docs/api/reference#start-commercial",
    "token_type": "OA",
    "scope": "f2be15e3-efe4-4e1f-b3df-013981ebdc61"
  },
  ...
]

POST `/api/v1/twitch/helix-endpoints`

Create a new helix endpoint definition, be careful you probably don't want to do this, if you add a duplicate it will mess up the UI.

Request

curl --request POST http://<TAU_SERVER>/api/v1/twitch/helix-endpoints  -H 'Authorization: Token <AUTH_TOKEN>' -H 'Content-type: application/json' --data '{"description":"Get Webhook Subscriptions","endpoint":"webhooks/subscriptions","method":"GET","reference_url":"https://dev.twitch.tv/docs/api/reference#get-webhook-subscriptions","token_type":"AP","scope":null}'

Response

{
  "id": "5e256700-1cfe-4eef-bf0b-dd3c6f541377",
  "description": "Get Webhook Subscriptions",
  "endpoint": "webhooks/subscriptions",
  "method": "GET",
  "reference_url": "https://dev.twitch.tv/docs/api/reference#get-webhook-subscriptions",
  "token_type": "AP",
  "scope": null
}

GET `/api/v1/twitch/helix-endpoints/<ID>`

Get the details for a specific helix endpoint by ID

Request

curl http://<TAU_SERVER>/api/v1/twitch/helix-endpoints/<ID> -H 'Authorization: Token <AUTH_TOKEN>'

Response

{
  "id": "5e256700-1cfe-4eef-bf0b-dd3c6f541377",
  "description": "Get Webhook Subscriptions",
  "endpoint": "webhooks/subscriptions",
  "method": "GET",
  "reference_url": "https://dev.twitch.tv/docs/api/reference#get-webhook-subscriptions",
  "token_type": "AP",
  "scope": null
}

v1 Endpoints

Twitch Events

GET /api/v1/twitch-events

Request

Response

Request

POST /api/v1/twitch-events

Request

Response:

POST /api/v1/twitch-events/<EVENT_TYPE>/test

Request

Response

Heartbeats

GET /api/v1/heartbeat

Request

Response

Streamers

GET /api/v1/streamers

Request

Response

POST /api/v1/streamers

Request

Response

GET /api/v1/streamers/<ID>

Request

Response

GET /api/v1/streamers/<ID>/streams

Request

Response

GET /api/v1/streamers/<ID>/streams/latest

Request

Response

Twitch Scopes

GET /api/v1/twitch/scopes

Request

Response

POST /api/v1/twitch/scopes

Request

Response

GET /api/v1/twitch/scopes/<ID>

Request

Response

Helix Endpoints

GET /api/v1/twitch/helix-endpoints

Request

Response

POST /api/v1/twitch/helix-endpoints

Request

Response

GET /api/v1/twitch/helix-endpoints/<ID>

Request

Response

GET `/api/v1/twitch-events`

POST `/api/v1/twitch-events`

POST `/api/v1/twitch-events/<EVENT_TYPE>/test`

GET `/api/v1/heartbeat`

GET `/api/v1/streamers`

POST `/api/v1/streamers`

GET `/api/v1/streamers/<ID>`

GET `/api/v1/streamers/<ID>/streams`

GET `/api/v1/streamers/<ID>/streams/latest`

GET `/api/v1/twitch/scopes`

POST `/api/v1/twitch/scopes`

GET `/api/v1/twitch/scopes/<ID>`

GET `/api/v1/twitch/helix-endpoints`

POST `/api/v1/twitch/helix-endpoints`

GET `/api/v1/twitch/helix-endpoints/<ID>`