KickClient¶
The main client class for interacting with the Kick API.
kickpy.client.KickClient(client_id, client_secret)
¶
authenticate(scopes, redirect_uri=None, port=3000, timeout=300)
async
¶
Authenticate with Kick using OAuth 2.1 + PKCE.
Opens the user's browser to authorize, captures the callback on a local server, and exchanges the code for tokens.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scopes
|
list[Scope | str]
|
The scopes to request. |
required |
redirect_uri
|
str | None
|
The redirect URI. Defaults to |
None
|
port
|
int
|
The local port for the callback server. Defaults to 3000. |
3000
|
timeout
|
float
|
Maximum seconds to wait for the user to authorize. Defaults to 300 (5 minutes). |
300
|
set_user_token(access_token, refresh_token, expires_in, scope)
¶
Manually set a user token for users who handle OAuth externally.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
access_token
|
str
|
The access token. |
required |
refresh_token
|
str
|
The refresh token. |
required |
expires_in
|
int
|
Seconds until the token expires. |
required |
scope
|
str
|
The scopes granted. |
required |
close()
async
¶
Close the client and all sessions.
fetch_public_key()
async
¶
Get the public key of the Kick.com API.
Returns:
| Type | Description |
|---|---|
bytes
|
The public key data. |
fetch_user(user_id)
async
¶
Get a user by their ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
user_id
|
int
|
The ID of the user to get. |
required |
Returns:
| Type | Description |
|---|---|
User
|
The user data. |
fetch_channel(user_id=None, slug=None)
async
¶
Get a channel by the broadcaster user ID or slug.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
user_id
|
int | None
|
The broadcaster user ID. |
None
|
slug
|
str | None
|
The broadcaster user slug. |
None
|
Returns:
| Type | Description |
|---|---|
Channel
|
The channel data. |
update_channel(*, category_id=None, stream_title=None, custom_tags=None)
async
¶
Update channel metadata. Requires channel:write scope.
At least one parameter must be provided.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
category_id
|
int | None
|
The new category ID. |
None
|
stream_title
|
str | None
|
The new stream title. |
None
|
custom_tags
|
list[str] | None
|
The new custom tags (max 10). |
None
|
fetch_livestream(broadcaster_user_id)
async
¶
Get livestream by the broadcaster user ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
broadcaster_user_id
|
int
|
The broadcaster user ID to get livestream from. |
required |
Returns:
| Type | Description |
|---|---|
LiveStream
|
The livestream data. |
fetch_livestreams(broadcaster_user_id=None, category_id=None, language=None, limit=None, sort='viewer_count')
async
¶
Get livestreams.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
broadcaster_user_id
|
int | list[int] | None
|
One or more broadcaster user IDs (up to 50). |
None
|
category_id
|
int | None
|
The category ID to filter by. |
None
|
language
|
str | None
|
The language to filter by. |
None
|
limit
|
int | None
|
The maximum number of results (1-100, default 25). |
None
|
sort
|
str
|
Sort order. Either |
'viewer_count'
|
Returns:
| Type | Description |
|---|---|
list[LiveStream]
|
A list of livestream data. |
fetch_livestream_stats()
async
¶
fetch_categories(query=None, *, name=None, tag=None, category_id=None, cursor=None, limit=25)
async
¶
Get categories using the v2 endpoint.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query
|
str | None
|
Shorthand for searching by name. Equivalent to |
None
|
name
|
list[str] | None
|
Category names to search for. |
None
|
tag
|
list[str] | None
|
Category tags to filter by. |
None
|
category_id
|
list[int] | None
|
Category IDs to filter by. |
None
|
cursor
|
str | None
|
Pagination cursor. |
None
|
limit
|
int
|
Results limit (1-1000, default 25). |
25
|
Returns:
| Type | Description |
|---|---|
list[Category]
|
A list of categories. |
send_chat_message(content, message_type='bot', broadcaster_user_id=None, reply_to_message_id=None)
async
¶
Send a chat message. Requires chat:write scope.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
content
|
str
|
The message text (max 500 characters). |
required |
message_type
|
str
|
The sending mode: |
'bot'
|
broadcaster_user_id
|
int | None
|
Required when message_type is |
None
|
reply_to_message_id
|
str | None
|
Optional message ID to reply to. |
None
|
Returns:
| Type | Description |
|---|---|
ChatResponse
|
The response containing is_sent and message_id. |
delete_chat_message(message_id)
async
¶
Delete a chat message. Requires moderation:chat_message:manage scope.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message_id
|
str
|
The ID of the message to delete. |
required |
ban_user(broadcaster_user_id, user_id, *, duration=None, reason=None)
async
¶
Ban or timeout a user. Requires moderation:ban scope.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
broadcaster_user_id
|
int
|
The channel to ban in. |
required |
user_id
|
int
|
The user to ban. |
required |
duration
|
int | None
|
Timeout duration in minutes (1-10080). Omit for permanent ban. |
None
|
reason
|
str | None
|
The ban/timeout reason (max 100 characters). |
None
|
unban_user(broadcaster_user_id, user_id)
async
¶
Unban a user or remove a timeout. Requires moderation:ban scope.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
broadcaster_user_id
|
int
|
The channel to unban in. |
required |
user_id
|
int
|
The user to unban. |
required |
fetch_channel_rewards()
async
¶
Get channel point rewards. Requires channel:rewards:read scope.
Returns:
| Type | Description |
|---|---|
list[ChannelReward]
|
A list of channel rewards. |
create_channel_reward(cost, title, *, background_color=None, description=None, is_enabled=None, is_user_input_required=None, should_redemptions_skip_request_queue=None)
async
¶
Create a channel point reward. Requires channel:rewards:write scope.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cost
|
int
|
The cost in channel points (min 1). |
required |
title
|
str
|
The reward title (max 50 characters). |
required |
background_color
|
str | None
|
Hex color (default |
None
|
description
|
str | None
|
The reward description (max 200 characters). |
None
|
is_enabled
|
bool | None
|
Whether the reward is enabled (default True). |
None
|
is_user_input_required
|
bool | None
|
Whether user input is required (default False). |
None
|
should_redemptions_skip_request_queue
|
bool | None
|
Whether redemptions skip the queue (default False). |
None
|
Returns:
| Type | Description |
|---|---|
ChannelReward
|
The created reward. |
update_channel_reward(reward_id, *, background_color=None, cost=None, description=None, is_enabled=None, is_paused=None, is_user_input_required=None, should_redemptions_skip_request_queue=None, title=None)
async
¶
Update a channel point reward. Requires channel:rewards:write scope.
Only the app that created the reward can update it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
reward_id
|
str
|
The reward ID (ULID). |
required |
background_color
|
str | None
|
Hex color. |
None
|
cost
|
int | None
|
The cost in channel points. |
None
|
description
|
str | None
|
The reward description. |
None
|
is_enabled
|
bool | None
|
Whether the reward is enabled. |
None
|
is_paused
|
bool | None
|
Whether the reward is paused. |
None
|
is_user_input_required
|
bool | None
|
Whether user input is required. |
None
|
should_redemptions_skip_request_queue
|
bool | None
|
Whether redemptions skip the queue. |
None
|
title
|
str | None
|
The reward title. |
None
|
Returns:
| Type | Description |
|---|---|
ChannelReward
|
The updated reward. |
delete_channel_reward(reward_id)
async
¶
Delete a channel point reward. Requires channel:rewards:write scope.
Only the app that created the reward can delete it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
reward_id
|
str
|
The reward ID (ULID). |
required |
fetch_reward_redemptions(*, reward_id=None, status=None, ids=None, cursor=None)
async
¶
Get reward redemptions. Requires channel:rewards:read scope.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
reward_id
|
str | None
|
Filter by specific reward ID. |
None
|
status
|
str | None
|
Filter by status: |
None
|
ids
|
list[str] | None
|
Specific redemption IDs (cannot combine with other filters). |
None
|
cursor
|
str | None
|
Pagination cursor. |
None
|
Returns:
| Type | Description |
|---|---|
list[RedemptionsByReward]
|
Redemptions grouped by reward. |
accept_reward_redemptions(ids)
async
¶
Accept pending reward redemptions. Requires channel:rewards:write scope.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ids
|
list[str]
|
Redemption IDs to accept (1-25, must be unique). |
required |
Returns:
| Type | Description |
|---|---|
list[FailedRedemption]
|
A list of failed redemptions (empty if all succeeded). |
reject_reward_redemptions(ids)
async
¶
Reject pending reward redemptions. Requires channel:rewards:write scope.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ids
|
list[str]
|
Redemption IDs to reject (1-25, must be unique). |
required |
Returns:
| Type | Description |
|---|---|
list[FailedRedemption]
|
A list of failed redemptions (empty if all succeeded). |
fetch_kicks_leaderboard(top=10)
async
¶
Get the KICKs leaderboard. Requires kicks:read scope.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
top
|
int
|
Number of top entries (1-100, default 10). |
10
|
Returns:
| Type | Description |
|---|---|
KicksLeaderboard
|
The leaderboard with lifetime, month, and week rankings. |
fetch_events_subscriptions()
async
¶
Get event subscriptions.
Returns:
| Type | Description |
|---|---|
list[EventsSubscription]
|
A list of EventsSubscription data. |
subscribe_to_event(event_type, user_id)
async
¶
Subscribe to an event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event_type
|
WebhookEvent
|
The event type to subscribe to. |
required |
user_id
|
int
|
The user ID to subscribe to. |
required |
Returns:
| Type | Description |
|---|---|
EventsSubscriptionCreated
|
The created event subscription if successful, otherwise None. |
unsubscribe_from_event(subscription_id)
async
¶
Unsubscribe from an event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
subscription_id
|
str
|
The subscription ID to unsubscribe from. |
required |