API Reference

Complete reference for the NxCreator public API — API key authentication, bot management, and custom webhooks.

The NxCreator public API uses a personal API key for authentication. All endpoints live under the same base URL and accept JSON.

Base URL
https://api-prod-nexcreate-01.nx3r.com

Authentication

Pass your API key as apiKey in the JSON body (POST) or query string (GET). The authenticated user is resolved from the key — no separate uid needed.

An invalid or missing key returns 401 Invalid API Key.

Getting your API key

Your API key is available in the NxCreator dashboard. Open Settings, scroll to the API Key section, and click Copy. The key is generated automatically on first visit and remains stable until you regenerate it.

Treat your API key like a password. It grants full access to your bots and account. Never expose it in client-side code or public repositories.

apiv3 — Bot management

The /apiv3/:path route accepts both GET and POST. Pass apiKey in the body (POST) or query string (GET). The authenticated user is resolved from the key — no separate uid needed.

restartBot

POST /apiv3/restartBot
{ "apiKey": "...", "botId": "abc123" }

{ "ok": true, "msg": "Bot restarted", "stat_code": 200 }

transferBot

Copies the bot and its code to another NxCreator account. Optionally starts the bot immediately on the new account if run_now is true (requires newBotToken). You can also seed initial data into the new bot's collections using dbProps.

Field	Type	Required	Description
`apiKey`	string	Yes	Your API key.
`botId`	string	Yes	ID of the bot to transfer.
`targetEmail`	string	Yes	Email of the recipient NxCreator account.
`newBotToken`	string	No	Bot token for the new bot on the recipient account.
`run_now`	boolean	No	Start the new bot immediately. Requires `newBotToken`.
`dbProps`	object	No	Initial collection data to seed into the new bot. Keys are collection names (no underscores), values are arrays of documents.

POST /apiv3/transferBot
{
  "apiKey": "...",
  "botId": "abc123",
  "targetEmail": "[email protected]",
  "newBotToken": "123:AAA...",
  "run_now": true,
  "dbProps": {
    "settings": [{ "key": "welcomeMsg", "value": "Hello!" }],
    "admins":   [{ "userId": 9876543, "role": "owner" }]
  }
}

{
  "ok": true,
  "msg": "Bot transferred",
  "stat_code": 200,
  "newBotId": "def456",
  "dbProps": {
    "settings": { "inserted": 1 },
    "admins":   { "inserted": 1 }
  }
}

Collection names in dbProps must not contain underscores and follow the same rules as regular bot collection names. Each document array is seeded into the corresponding collection on the new bot. Errors per collection are reported individually without blocking the rest of the transfer.

editBotCoreLogic

Overwrites the full bot code file. The bot must be restarted separately for changes to take effect.

POST /apiv3/editBotCoreLogic
{ "apiKey": "...", "botId": "abc123", "newCode": "bot.command('start', ctx => ctx.reply('Hi'));" }

{ "ok": true, "msg": "Code updated", "stat_code": 200 }

getbotCode

POST /apiv3/getbotCode
{ "apiKey": "...", "botId": "abc123" }

{ "ok": true, "msg": "Code fetched", "stat_code": 200, "data": "// bot code..." }

Custom Webhooks

Every bot can expose HTTP endpoints you define directly in bot code. No API key is required to call them — auth is up to you inside the handler.

Webhook base URL
https://api-prod2-next-bot.nx3r.com

Route pattern (all HTTP methods accepted)
/custom/:botId/:customPath

Webhook handler contract

Assign an async function to logic['yourPath'] in your bot code:

logic['notify'] = async (query, body, db, response, params) => {
  const userId = body.userId;
  if (!userId) {
    response.statusCode = 400;
    response.message = 'userId is required';
    return;
  }
  const user = await db.operation.findOne('users', { userId });
  await bot.telegram.sendMessage(userId, `Hello ${user?.name ?? 'there'}!`);
  response.statusCode = 200;
  response.data = { sent: true };
};

curl -X POST "https://api-prod2-next-bot.nx3r.com/custom/<botId>/notify" \
  -H "Content-Type: application/json" \
  -d '{"userId": 9876543}'

Response object

Mutate the response object inside your handler to control the HTTP response:

Field	Type	Description
`statusCode`	number	HTTP status code. Defaults to 200. The top-level `ok` field is `true` when < 400.
`headers`	object	Extra response headers (e.g. `{ "X-Request-Id": "abc" }`).
`message`	string	Short human-readable message included in the JSON body.
`data`	any	Payload returned under the `data` key. If unset and the handler returns a value, that return value is used automatically.

HTTP status	Cause
400	Invalid path format, or no `logic` handler registered for the requested path.
403	Bot is under halt — restart it from the dashboard to resume.
404	Bot ID not found.
500	Compile or runtime error inside the handler. Full details appear in the bot error log.

Common use cases

Custom webhooks let any external service trigger bot actions over HTTP. Because they run inside the full bot runtime, you have access to bot.telegram, the db helper, and axios — everything your normal bot code can use.

Push notifications from an external service

Trigger a Telegram message to a user from a payment gateway, CI pipeline, or any backend event.

logic['notify'] = async (query, body, db, response) => {
  const { userId, text } = body;
  if (!userId || !text) { response.statusCode = 400; response.message = 'userId and text required'; return; }
  await bot.telegram.sendMessage(userId, text);
  response.data = { sent: true };
};

Broadcast a message to all bot users

logic['broadcast'] = async (query, body, db, response) => {
  const { text } = body;
  if (!text) { response.statusCode = 400; response.message = 'text required'; return; }
  const users = await db.operation.findAll('users', {});
  let sent = 0;
  for (const u of users) {
    try { await bot.telegram.sendMessage(u.userId, text); sent++; } catch {}
  }
  response.data = { sent, total: users.length };
};

Receive third-party webhooks

Use a custom webhook as the callback URL for Stripe, GitHub, or any other service. Validate the payload and store or act on it inside the handler.

logic['stripe-event'] = async (query, body, db, response) => {
  if (body.type === 'checkout.session.completed') {
    const userId = Number(body.data?.object?.metadata?.telegramUserId);
    if (userId) {
      await db.operation.setProp('users', { userId }, 'isPremium', true);
      await bot.telegram.sendMessage(userId, 'Payment confirmed — you are now premium!');
    }
  }
  response.data = { received: true };
};

Expose bot data as a mini API

Read from your bot's collections and return JSON — useful for a companion web app or dashboard.

logic['stats'] = async (query, body, db, response) => {
  const total = await db.operation.countDocuments('users', {});
  const premium = await db.operation.countDocuments('users', { isPremium: true });
  response.data = { total, premium };
};

Simple token-based auth

Custom webhook routes have no built-in auth. Add your own secret check at the top of any handler that should be private.

const SECRET = 'my-secret-token';

logic['admin-action'] = async (query, body, db, response) => {
  if (query.token !== SECRET) {
    response.statusCode = 401;
    response.message = 'Unauthorized';
    return;
  }
  // safe to proceed
  response.data = { ok: true };
};

Store your webhook secret in the bot's env vars and read it with process.env.MY_SECRET instead of hardcoding it.

Last updated March 22, 2026

Was this page helpful?