API reference v1

Every endpoint lives under this base URL:

https://api.sukson.dev/v1

All endpoints

Method	Path	Purpose
GET	/v1/me	The bot
GET	/v1/me/quota	The bot’s quota and plan
GET	/v1/me/quota/consumption	Usage this month
PUT	/v1/me/commands	Set the /command list
GET	/v1/me/webhook	The current webhook
PUT	/v1/me/webhook	Set the webhook URL
DELETE	/v1/me/webhook	Stop using the webhook
POST	/v1/me/webhook/test	Send a test ping
GET	/v1/me/chats	The chats the bot is in
POST	/v1/chats/{chat_id}/messages	Send messages (reply or push)
PATCH	/v1/messages/{message_id}	Edit a bot message
DELETE	/v1/messages/{message_id}	Delete a bot message

There’s no endpoint to read message history. A bot only sees the events sent to it.

Requests

• Send Authorization: Bearer skbot_... with every request (authentication).
• Requests with a body send Content-Type: application/json and one JSON object of at most 64 KB.
• A field the endpoint doesn’t know gets 422 UNKNOWN_FIELD instead of being quietly ignored, so you spot typos early.
• chat_id is a string, message_id a positive integer.
• Times are ISO 8601 in UTC.

Responses

A successful answer is the data object itself, with nothing wrapped around it.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
X-Request-Id: 01JC0Z8W5T9V3QH2M6K4R7N1PB
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 2

{ "id": "01933b40-1a2b-7c3d-8e4f-5a6b7c8d9e0f", "handle": "weather_bot", "name": "WeatherBot", "status": "active", "commands": [] }

An error is always {message, code, details?} with a meaningful HTTP status (errors).

{ "message": "Too many requests; slow down", "code": "RATE_LIMITED", "details": { "retry_after": 3 } }

Header	Meaning
X-Request-Id	The request’s id; include it when you contact us. You may send your own in the request.
X-RateLimit-Limit	The bot’s requests per minute
X-RateLimit-Remaining	What’s left right now
X-RateLimit-Reset	Seconds until the allowance is full again
Retry-After	With 429: seconds to wait before trying again