Developer Documentation

StreamKit Public API v2

Integrate StreamKit data into your own apps using per-user credentials. Fetch stream status, subscriptions, coins, loyalty stats, and historical events. Client secrets are rotatable and JWTs are revocable from the dashboard at any time.

API version: v2 · current v1 · legacy

Base URL http://bot.expanzor.cz/api/public/v2

OpenAPI JSON Authentication guide

Getting started

Authentication

Every request requires all three credentials passed as headers:

X-Client-Id X-Client-Secret Authorization: Bearer <JWT>

Example request

curl "http://bot.expanzor.cz/api/public/v2/overview" \
  -H "X-Client-Id: YOUR_CLIENT_ID" \
  -H "X-Client-Secret: YOUR_CLIENT_SECRET" \
  -H "Authorization: Bearer YOUR_JWT"

You can also pass client_id, client_secret, and jwt as query parameters — but headers are strongly preferred for security.

Standard response shape

All endpoints return a consistent JSON envelope:

{'{'|noescape}
  "ok": true,
  "version": "v2",
  "generated_at": "2026-06-06T00:00:00+02:00",
  "broadcaster": {
    "user_id": 123,
    "name": "Streamer",
    "primary_platform": "twitch",
    "platforms": {
      "kick":   { "username": "streamer_name", "id": "84635624" },
      "twitch": { "username": "streamer_tv",  "id": "29958160" }
    },
    "kick_username": "streamer_name",
    "kick_user_id": "84635624"
  },
  "data": { ... }
{'}'|noescape}

Works with a Kick or Twitch account (or both). kick_username/kick_user_id are kept for v1 compatibility; prefer platforms and primary_platform.

Core

GET /api/public/v2/overview

Overview

Quick summary across stream status, subscriptions, coins, kicks and event totals.

Query parameters

No query parameters for this endpoint.

Example request

GET /api/public/v2/overview

Example response

{
    "ok": true,
    "version": "v2",
    "generated_at": "2026-06-06T00:00:00+02:00",
    "broadcaster": {
        "user_id": 123,
        "name": "Streamer",
        "primary_platform": "twitch",
        "platforms": {
            "kick": {
                "username": "streamer_name",
                "id": "84635624"
            },
            "twitch": {
                "username": "streamer_tv",
                "id": "29958160"
            }
        },
        "kick_username": "streamer_name",
        "kick_user_id": "84635624"
    },
    "data": {
        "stream_status": {
            "is_live": true,
            "platforms": {
                "kick": {
                    "is_live": false
                },
                "twitch": {
                    "is_live": true,
                    "viewer_count": 134,
                    "stream_title": "Ranked grind",
                    "category_name": "League of Legends"
                }
            }
        },
        "subscriptions": {
            "active": 42,
            "gifted": 12,
            "new": 7,
            "resubs": 5,
            "all": 24,
            "by_platform": {
                "kick": {
                    "active_total": 30
                },
                "twitch": {
                    "active_total": 12
                }
            }
        },
        "coins": {
            "total_coins": 15320,
            "users_count": 188
        },
        "kicks": {
            "total_kicks": 342
        },
        "events": {
            "total": 1389
        }
    }
}

GET /api/public/v2/stream-status

Stream status

Live/offline state for every connected platform (Kick + Twitch) plus a combined is_live flag.

Query parameters

No query parameters for this endpoint.

Example request

GET /api/public/v2/stream-status

Example response

{
    "ok": true,
    "data": {
        "is_live": true,
        "platforms": {
            "kick": {
                "is_live": false
            },
            "twitch": {
                "is_live": true,
                "viewer_count": 134,
                "stream_title": "Ranked grind",
                "category_name": "League of Legends"
            }
        }
    }
}

Subscriptions

GET /api/public/v2/subscriptions-summary

Subscription summary

High-level counters for active subs, gifted subs, new subs, resubs and observed history, broken down per platform.

Query parameters

No query parameters for this endpoint.

Example request

GET /api/public/v2/subscriptions-summary

Example response

{
    "ok": true,
    "data": {
        "active": 42,
        "gifted": 12,
        "new": 7,
        "resubs": 5,
        "all": 24,
        "by_platform": {
            "kick": {
                "active_total": 30
            },
            "twitch": {
                "active_total": 12
            }
        },
        "history_count": 119
    }
}

GET /api/public/v2/subscriptions-active

Active subscriptions

Estimated active subscriber preview with expiration hints.

Query parameters

No query parameters for this endpoint.

Example request

GET /api/public/v2/subscriptions-active

Example response

{
    "ok": true,
    "data": {
        "active_total": 42,
        "preview": [
            {
                "username": "viewer123",
                "expires_at": "2026-07-10T18:30:00+02:00"
            }
        ]
    }
}

GET /api/public/v2/subscriptions-history

Subscription history

Historical subscription events including new, renewal and gifted records with a platform field.

Query parameters

Name	Type	Required	Description	Default
`limit`	integer	optional	Number of rows to return.	50

Example request

GET /api/public/v2/subscriptions-history?limit=50

Example response

{
    "ok": true,
    "data": [
        {
            "type": "channel.subscription.gifts",
            "platform": "twitch",
            "actor": "viewer123",
            "count": 5,
            "received_at": "2026-06-06T18:30:00+02:00"
        }
    ]
}

Economy

GET /api/public/v2/coins

Coins

Loyalty coin totals and leaderboard of top viewers.

Query parameters

Name	Type	Required	Description	Default
`limit`	integer	optional	Leaderboard size.	25

Example request

GET /api/public/v2/coins?limit=25

Example response

{
    "ok": true,
    "data": {
        "summary": {
            "total_coins": 15320,
            "users_count": 188
        },
        "leaderboard": [
            {
                "username": "viewer123",
                "coins": 450
            }
        ]
    }
}

GET /api/public/v2/kicks

Kicks

Kick gifting summary, top gifters and observed historical kick events (Kick-specific; Twitch cheers arrive via events-history as channel.cheered).

Query parameters

Name	Type	Required	Description	Default
`limit`	integer	optional	History size.	25

Example request

GET /api/public/v2/kicks?limit=25

Example response

{
    "ok": true,
    "data": {
        "summary": {
            "total_kicks": 342,
            "gift_events": 19
        },
        "top_gifters": [
            {
                "username": "viewer999",
                "kicks": 55
            }
        ],
        "history": [
            {
                "actor": "viewer999",
                "amount": 5
            }
        ]
    }
}

Engagement

GET /api/public/v2/song-request

Song Request queue

Current queue of requested songs.

Query parameters

Name	Type	Required	Description	Default
`limit`	integer	optional	Queue size.	10

Example request

GET /api/public/v2/song-request?limit=10

Example response

{
    "ok": true,
    "data": [
        {
            "requester_username": "viewer123",
            "provider": "youtube",
            "song_url": "https://youtu.be/..."
        }
    ]
}

GET /api/public/v2/giveaway

Giveaway state

Current giveaway settings, entries and winner.

Query parameters

No query parameters for this endpoint.

Example request

GET /api/public/v2/giveaway

Example response

{
    "ok": true,
    "data": {
        "settings": {
            "title": "Giveaway",
            "keyword": "!join"
        },
        "entries": [
            {
                "username": "viewer1"
            }
        ]
    }
}

GET /api/public/v2/wheel

Wheel state

Wheel title, configured segments and last result.

Query parameters

No query parameters for this endpoint.

Example request

GET /api/public/v2/wheel

Example response

{
    "ok": true,
    "data": {
        "title": "Wheel of Fortune",
        "segments": [
            "100 coins",
            "Hydrate"
        ],
        "last_result": "Hydrate"
    }
}

GET /api/public/v2/gamble

Gamble history

Latest gamble results for overlay widgets or dashboards.

Query parameters

Name	Type	Required	Description	Default
`limit`	integer	optional	History size.	10

Example request

GET /api/public/v2/gamble?limit=10

Example response

{
    "ok": true,
    "data": [
        {
            "username": "viewer1",
            "game_type": "coinflip",
            "outcome": "win"
        }
    ]
}

POST /api/public/v2/stream-info

Update stream info

Updates title and/or category on the primary connected broadcaster account.

Query parameters

No query parameters for this endpoint.

Example request

POST /api/public/v2/stream-info {"title":"Just Chatting with chat","category":"Just Chatting"}

Example response

{
    "ok": true,
    "data": {
        "updated": true,
        "title": "Just Chatting with chat",
        "category": "Just Chatting"
    }
}

Events

GET /api/public/v2/events-history

Historical events

Latest stored events (Kick + Twitch). You can optionally filter by event type.

Query parameters

Name	Type	Required	Description	Default
`limit`	integer	optional	Max number of items.	50
`type`	string	optional	Exact event type filter, e.g. chat.message.sent.	—

Example request

GET /api/public/v2/events-history?limit=50&type=chat.message.sent

Example response

{
    "ok": true,
    "data": [
        {
            "type": "chat.message.sent",
            "platform": "twitch",
            "actor": "viewer1",
            "message": "!watchtime",
            "received_at": "2026-06-06T18:35:00+02:00"
        }
    ]
}

Error responses

401 Unauthorized

{
  "ok": false,
  "error": "missing_credentials",
  "message": "Missing client_id, client_secret, or JWT token."
}

401 Revoked JWT

{
  "ok": false,
  "error": "revoked_jwt",
  "message": "JWT token was revoked. Generate a new one in the dashboard."
}

OpenAPI / SDKs

Machine-readable spec

Import into Swagger UI, Postman, Insomnia, or use with any OpenAPI code generator.

Spec URL

http://bot.expanzor.cz/api/public/openapi?version=v2

Download OpenAPI JSON →