Bot API

Bot API Docs

Public reference for owner-side management and bot-token runtime endpoints.

All endpointsOwnerBot runtimeWebhooksLong pollingTS SDKOpenAPI JSONRedocSwagger UI
List bots
OwnerGET/v1/bot-api/bots

Returns every bot owned by the current account.

Authorization: Bearer owner token

Status codes
200Returns every bot owned by the current account.
401Missing or invalid bearer token.
429Rate limit exceeded.
curl
curl -H "Authorization: Bearer <owner_token>" https://api.yullama.ru/v1/bot-api/bots
JSON response
{
  "items": [
    {
      "bot_user_id": "b63c...",
      "created_at": "2026-04-21T10:00:00Z",
      "description": "Publishes Russia news",
      "display_name": "News Bot Russia",
      "id": "7f9d...",
      "owner_user_id": "25c0...",
      "updated_at": "2026-04-21T10:30:00Z",
      "username": "newsbot_russia_v1",
      "webhook_url": "https://bot.example.test/webhook"
    }
  ]
}
Create bot
OwnerPOST/v1/bot-api/bots

Creates a new bot and returns the initial token once.

Authorization: Bearer owner token

Status codes
201Creates a new bot and returns the initial token once.
400Malformed input or invalid parameter value.
401Missing or invalid bearer token.
429Rate limit exceeded.
curl
curl -X POST https://api.yullama.ru/v1/bot-api/bots \
  -H "Authorization: Bearer <owner_token>" \
  -H "Content-Type: application/json" \
  -d '{"username":"news_tatarstan_bot","display_name":"News Bot","description":"Publishes verified news"}'
JSON request
{
  "description": "Publishes verified news",
  "display_name": "News Bot",
  "username": "news_tatarstan_bot"
}
JSON response
{
  "bot": {
    "bot_user_id": "b63c...",
    "created_at": "2026-04-21T10:00:00Z",
    "description": "Publishes verified news",
    "display_name": "News Bot",
    "id": "7f9d...",
    "owner_user_id": "25c0...",
    "updated_at": "2026-04-21T10:00:00Z",
    "username": "news_tatarstan_bot"
  },
  "token": {
    "created_at": "2026-04-21T10:00:00Z",
    "token": "bot_..."
  }
}
Get bot
OwnerGET/v1/bot-api/bots/{id}

Returns one bot owned by the current account.

Authorization: Bearer owner token

Parameters
idpath · requiredBot identifier.
Status codes
200Returns one bot owned by the current account.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -H "Authorization: Bearer <owner_token>" https://api.yullama.ru/v1/bot-api/bots/<bot_id>
JSON response
{
  "bot_user_id": "b63c...",
  "created_at": "2026-04-21T10:00:00Z",
  "description": "Publishes Russia news",
  "display_name": "News Bot Russia",
  "id": "7f9d...",
  "owner_user_id": "25c0...",
  "updated_at": "2026-04-21T10:30:00Z",
  "username": "newsbot_russia_v1",
  "webhook_url": "https://bot.example.test/webhook"
}
List attached channels
OwnerGET/v1/bot-api/bots/{id}/channels

Lists channels attached to one bot.

Authorization: Bearer owner token

Parameters
idpath · requiredBot identifier.
Status codes
200Lists channels attached to one bot.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -H "Authorization: Bearer <owner_token>" https://api.yullama.ru/v1/bot-api/bots/<bot_id>/channels
JSON response
{
  "items": [
    {
      "bot_role": "moderator",
      "created_at": "2026-04-21T10:00:00Z",
      "description": "Owned channel for bot publishing",
      "id": "22d6...",
      "slug": "news-russia",
      "title": "News Russia"
    }
  ]
}
Attach bot to channel
OwnerPOST/v1/bot-api/bots/{id}/channels/{channelId}

Attaches a bot to one owned channel with moderator role.

Authorization: Bearer owner token

Parameters
idpath · requiredBot identifier.
channelIdpath · requiredChannel identifier.
Status codes
200Attaches a bot to one owned channel with moderator role.
400Malformed input or invalid parameter value.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -X POST https://api.yullama.ru/v1/bot-api/bots/<bot_id>/channels/<channel_id> \
  -H "Authorization: Bearer <owner_token>"
JSON response
{
  "attached_by": "25c0...",
  "bot_id": "7f9d...",
  "channel_id": "22d6...",
  "role": "moderator"
}
Bot stats
OwnerGET/v1/bot-api/bots/{id}/stats

Returns queue and delivery counters for one bot.

Authorization: Bearer owner token

Parameters
idpath · requiredBot identifier.
Status codes
200Returns queue and delivery counters for one bot.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -H "Authorization: Bearer <owner_token>" https://api.yullama.ru/v1/bot-api/bots/<bot_id>/stats
JSON response
{
  "attached_channel_count": 2,
  "bot_id": "7f9d...",
  "delivered_updates": 16,
  "last_attempted_at": "2026-04-21T10:42:02Z",
  "last_delivered_at": "2026-04-21T10:42:02Z",
  "last_update_at": "2026-04-21T10:42:00Z",
  "pending_updates": 1,
  "scheduled_retries": 1,
  "terminal_failed_updates": 1,
  "total_updates": 18
}
Rotate bot token
OwnerPOST/v1/bot-api/bots/{id}/token

Issues a new bot token and invalidates the previous one.

Authorization: Bearer owner token

Parameters
idpath · requiredBot identifier.
Status codes
200Issues a new bot token and invalidates the previous one.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -X POST https://api.yullama.ru/v1/bot-api/bots/<bot_id>/token -H "Authorization: Bearer <owner_token>"
JSON response
{
  "created_at": "2026-04-21T10:30:00Z",
  "token": "bot_..."
}
Recent updates
OwnerGET/v1/bot-api/bots/{id}/updates

Returns recent bot_api_updates rows with payload and delivery state.

Authorization: Bearer owner token

Parameters
idpath · requiredBot identifier.
limitquery · optionalMaximum number of items to return.
Status codes
200Returns recent bot_api_updates rows with payload and delivery state.
400Malformed input or invalid parameter value.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -H "Authorization: Bearer <owner_token>" https://api.yullama.ru/v1/bot-api/bots/<bot_id>/updates?limit=20
JSON response
{
  "items": [
    {
      "created_at": "2026-04-21T10:42:00Z",
      "delivered_webhook_at": "2026-04-21T10:42:02Z",
      "event_type": "channel.post_created",
      "last_attempted_at": "2026-04-21T10:42:02Z",
      "last_delivery_error": "",
      "payload": {
        "body": "Owner update for history",
        "channel_id": "22d6...",
        "post_id": "90ab..."
      },
      "update_id": 41,
      "webhook_attempt_count": 1
    }
  ]
}
Get webhook config
OwnerGET/v1/bot-api/bots/{id}/webhook

Returns webhook URL, secret presence, and delivery health.

Authorization: Bearer owner token

Parameters
idpath · requiredBot identifier.
Status codes
200Returns webhook URL, secret presence, and delivery health.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -H "Authorization: Bearer <owner_token>" https://api.yullama.ru/v1/bot-api/bots/<bot_id>/webhook
JSON response
{
  "has_secret_token": true,
  "last_attempted_at": "2026-04-21T10:42:02Z",
  "last_delivered_at": "2026-04-21T10:42:02Z",
  "last_delivery_error": "",
  "next_retry_at": null,
  "pending_update_count": 0,
  "url": "https://bot.example.test/webhook"
}
Update webhook config
OwnerPUT/v1/bot-api/bots/{id}/webhook

Sets webhook URL and optional secret token.

Authorization: Bearer owner token

Parameters
idpath · requiredBot identifier.
Status codes
200Sets webhook URL and optional secret token.
400Malformed input or invalid parameter value.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -X PUT https://api.yullama.ru/v1/bot-api/bots/<bot_id>/webhook \
  -H "Authorization: Bearer <owner_token>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://bot.example.test/webhook","secret_token":"secret-123"}'
JSON request
{
  "secret_token": "secret-123",
  "url": "https://bot.example.test/webhook"
}
JSON response
{
  "has_secret_token": true,
  "last_attempted_at": "2026-04-21T10:42:02Z",
  "last_delivered_at": "2026-04-21T10:42:02Z",
  "last_delivery_error": "",
  "next_retry_at": null,
  "pending_update_count": 0,
  "url": "https://bot.example.test/webhook"
}
Delete webhook config
OwnerDELETE/v1/bot-api/bots/{id}/webhook

Disables webhook delivery for one bot.

Authorization: Bearer owner token

Parameters
idpath · requiredBot identifier.
Status codes
200Disables webhook delivery for one bot.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -X DELETE https://api.yullama.ru/v1/bot-api/bots/<bot_id>/webhook -H "Authorization: Bearer <owner_token>"
JSON response
{
  "status": "ok"
}
Webhook error log
OwnerGET/v1/bot-api/bots/{id}/webhook/errors

Returns concrete webhook delivery failures.

Authorization: Bearer owner token

Parameters
idpath · requiredBot identifier.
limitquery · optionalMaximum number of items to return.
Status codes
200Returns concrete webhook delivery failures.
400Malformed input or invalid parameter value.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -H "Authorization: Bearer <owner_token>" https://api.yullama.ru/v1/bot-api/bots/<bot_id>/webhook/errors?limit=20
JSON response
{
  "items": [
    {
      "created_at": "2026-04-21T10:52:00Z",
      "event_type": "channel.post_created",
      "last_attempted_at": "2026-04-21T10:52:02Z",
      "last_delivery_error": "500 Internal Server Error",
      "next_retry_at": "2026-04-21T10:52:04Z",
      "update_id": 44,
      "webhook_attempt_count": 1
    }
  ]
}
Replay failed webhook deliveries
OwnerPOST/v1/bot-api/bots/{id}/webhook/replay

Resets failed rows back into the delivery queue.

Authorization: Bearer owner token

Parameters
idpath · requiredBot identifier.
limitquery · optionalMaximum number of failed updates to requeue.
Status codes
200Resets failed rows back into the delivery queue.
400Malformed input or invalid parameter value.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -X POST "https://api.yullama.ru/v1/bot-api/bots/<bot_id>/webhook/replay?limit=100" \
  -H "Authorization: Bearer <owner_token>"
JSON response
{
  "bot_id": "7f9d...",
  "max_window": 6,
  "requeued": 3
}