Versioning

Every path starts with the version, e.g. https://api.sukson.dev/v1/me. Calling a version that doesn’t exist gets 404 UNKNOWN_VERSION.

There is one version today: v1. Because the version is in the path, code written for v1 won’t break from changes within v1, and when a new version comes out, v1 keeps working for a while.

What may be added within v1

These can appear in v1 at any time:

• New endpoints
• New fields in answers or events
• New optional fields in requests
• New enum values, e.g. for kind, trigger, status and event type
• New error codes
• New HTTP headers

So your code should ignore fields and values it doesn’t know, and answer 200 to event types it doesn’t know.

What needs a new version (breaking changes)

Changes that could break existing code only come in a new version, for example:

• Removing or renaming an endpoint or a field
• Changing a field’s type or meaning
• Making an optional field required
• Changing the webhook signature scheme (signatures carry their own version, v1=)

Retiring old versions

• Once /v2 exists, /v1 keeps working for a while; how long is announced together with /v2.
• Retirement dates are announced ahead of time in the changelog.
• After the retirement date, that version answers 404 UNKNOWN_VERSION.

The old Bot API (/bot-api/*)

The old Bot API at api.sukson.com/bot-api/* (getMe, sendMessage and so on) keeps working during the transition and will close after an announcement. This table shows where each old call lives in v1:

Old Bot API	API v1
GET /bot-api/getMe	GET /v1/me
GET /bot-api/getChats	GET /v1/me/chats
POST /bot-api/sendMessage	POST /v1/chats/{chat_id}/messages
POST /bot-api/editMessage	PATCH /v1/messages/{message_id}
POST /bot-api/deleteMessage	DELETE /v1/messages/{message_id}
POST /bot-api/setWebhook	PUT /v1/me/webhook
GET /bot-api/getWebhookInfo	GET /v1/me/webhook
POST /bot-api/deleteWebhook	DELETE /v1/me/webhook
POST /bot-api/setCommands	PUT /v1/me/commands

The main differences: v1 answers have no {success, data} envelope, and errors are {message, code, details}. Your token and webhook secret carry over unchanged.