API Reference

Programmatic access to cThrone features. All requests must be authenticated.

Why Use the API?

cThrone provides a set of APIs that enable your bots to leverage custom functionality without building it yourself. These APIs handle common features that you would otherwise need to implement and maintain on your side.

Global Bot Config

Manage global settings like maintenance mode, feature flags, or support contacts dynamically.

Store Subscriber Data

Save user balances, preferences, subscription levels, and any custom data — no database setup required.

Focus on Bot Logic

Skip building data layers and admin panels. Just call our API and focus on your bot's core features.

Request Structure

Interact with the API by sending HTTP requests to your bot's unique URL, always authorized with your token.

Target URL

https://your-bot-url.cthrone.dev/api/v1/...

Authentication

Bearer Token

Header or Auth

Authentication

All API requests must be authenticated using your bot token from the platform. For Telegram bots, this is the token you received from @BotFather.

Authorization: Bearer YOUR_BOT_TOKEN

Alternative: You can also pass the token via the X-Bot-Token header.

Bot Custom Config

Store and retrieve global configuration for your bot. This data is available to your bot instance regardless of the user context.

Example Use Cases:

Feature Flags — Enable or disable specific bot features globally
Maintenance Mode — Temporarily disable bot interactions during updates
Support Contact — Store current support email or channel link
Welcome Message — Customize the greeting message without redeploying code
Default Settings — Set global defaults for language or timezone

GET/api/v1/bot/custom-config

Get the current custom configuration for the bot.

Response Example

{
  "maintenanceMode": false,
  "defaultLanguage": "en",
  "supportEmail": "support@example.com",
  "welcomeMessage": "Hello! How can I help you?"
}

PUT/api/v1/bot/custom-config

Replace the bot's custom configuration. This overwrites existing configuration.

Request Body

{
  "maintenanceMode": true,
  "defaultLanguage": "es",
  "supportEmail": "contact@example.com",
  "welcomeMessage": "Hola! En qué puedo ayudarte?"
}

Subscriber Custom Fields

Custom Fields allow you to store arbitrary data about each subscriber of your bot. This is useful for persisting user-specific information without setting up your own database.

Example Use Cases:

User Balance — Store virtual currency or credits for each user
Subscription Level — Track premium, gold, or free tier status
User Preferences — Save language settings, notification preferences, or themes
Game Progress — Persist scores, levels, or achievements
Custom Notes — Add admin notes or tags for CRM purposes

GET/api/v1/subscribers/:platformUserId/custom-fields

Retrieve all custom fields for a specific subscriber.

Parameters

platformUserIdThe user ID from the platform (e.g. Telegram User ID like 123456789)

Response Example

{
  "balance": 150,
  "subscriptionLevel": "gold",
  "language": "en",
  "notifications": true
}

PUT/api/v1/subscribers/:platformUserId/custom-fields

Replace all custom fields for a subscriber. This overwrites existing fields with the new data.

Request Body

{
  "balance": 150,
  "subscriptionLevel": "gold",
  "language": "en",
  "notifications": false
}

Note: This is a full replacement. To update a single field, first GET the current fields, modify the value, then PUT the complete object.