API Reference

Complete reference for the NxCreator v2 REST API and the custom webhook system supported by globalHandler.

The NxCreator backend exposes a versioned REST API for bot management and a per-bot custom webhook system you can define directly from your bot code.

Authentication

All v2 API calls are POST requests that carry credentials in the JSON body. No header tokens are needed.

Field	Type	Description
`uid`	string	Your NxCreator user ID.
`authKey`	string	Session auth key returned at login.

Both fields are required on every request. A missing or expired session returns 401 Session Expired. Login Again.

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

v2 Endpoints

POST /v2/fetchAllBots

Returns a paginated list of all bots owned by the authenticated user, with optional status and search filters.

Body field	Type	Required	Description
`uid`	string	Yes	User ID.
`authKey`	string	Yes	Session key.
`page`	number	No	Page number. Default: 1.
`limit`	number	No	Results per page. Default: 20.
`status`	string	No	Filter by bot state: `"Active"` or `"Inactive"`.
`search`	string	No	Filter by bot name or username (case-insensitive).

// Response
{
  "ok": true,
  "stat_code": 200,
  "data": [
    {
      "botId": "abc123",
      "botName": "My Bot",
      "botUsername": "@mybot",
      "botIcon": "https://...",
      "botState": "Active",
      "totalUsers": 412,
      "webhookSet": true
    }
  ],
  "pagination": { "total": 3, "page": 1, "limit": 20, "totalPages": 1 }
}

POST /v2/getBotDetails

Returns full details for a single bot.

Body field	Type	Required	Description
`uid`	string	Yes	User ID.
`authKey`	string	Yes	Session key.
`botId`	string	Yes	The bot ID to look up.

// Response
{
  "ok": true,
  "stat_code": 200,
  "data": {
    "botId": "abc123",
    "botName": "My Bot",
    "botUsername": "@mybot",
    "botIcon": "https://...",
    "tgToken": "123:AAA...",
    "totalUsers": 412,
    "botState": "Active",
    "webhookUrl": "https://api-prod2-next-bot.nx3r.com/webhook/...",
    "webhookSet": true,
    "mode": "production",
    "sections": [...],
    "sectionsUpdatedAt": "2026-04-01T10:00:00.000Z"
  }
}

POST /v2/batchGetBotDetails

Returns details for multiple bots in a single request. Useful for dashboard list views.

Body field	Type	Required	Description
`uid`	string	Yes	User ID.
`authKey`	string	Yes	Session key.
`botIds`	string[]	Yes	Array of bot IDs to fetch.

// Response
{
  "ok": true,
  "stat_code": 200,
  "data": [
    { "botId": "abc123", "botName": "My Bot", "botState": "Active", "totalUsers": 412 }
  ]
}

POST /v2/fetchBotUsers

Returns a paginated list of users who have interacted with a bot. Each record includes the Telegram username, display name, profile photo, and join date fetched live from the Telegram API.

Body field	Type	Required	Description
`uid`	string	Yes	User ID.
`authKey`	string	Yes	Session key.
`botId`	string	Yes	Bot ID.
`page`	number	No	Page number. Default: 1.
`limit`	number	No	Results per page. Default: 30.

// Response
{
  "ok": true,
  "stat_code": 200,
  "data": [
    {
      "userId": 9876543,
      "username": "john_doe",
      "name": "John Doe",
      "startedAt": "1/4/2026, 9:12:00 AM",
      "profilePhoto": "https://api.telegram.org/file/bot.../..."
    }
  ],
  "pagination": { "total": 412, "page": 1, "limit": 30, "totalPages": 14 }
}

POST /v2/getBotStats

Returns aggregate statistics for a bot: total users, new users in the last 7 days, error count, and total log entries.

Body field	Type	Required	Description
`uid`	string	Yes	User ID.
`authKey`	string	Yes	Session key.
`botId`	string	Yes	Bot ID.

// Response
{
  "ok": true,
  "stat_code": 200,
  "data": {
    "totalUsers": 412,
    "newUsersLast7Days": 38,
    "totalErrors": 5,
    "totalLogs": 203
  }
}

Custom Webhooks

Every bot can expose its own HTTP endpoints without any extra server setup. You define handlers directly in your bot code and NxCreator routes incoming requests to them via globalHandler.

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

Route pattern
/custom/:botId/:customPath

The customPath value maps to a key you define on the logic object inside your bot code. All HTTP methods (GET, POST, PUT, etc.) are accepted on the same route.

Custom webhook endpoints do not require authentication at the route level. If your endpoint should be private, add your own token check inside the handler using the query or body parameters.

Webhook handler contract

Define a handler by assigning an async function to logic['yourPath']. The function receives four arguments:

Parameter	Type	Description
`query`	object	Parsed URL query string parameters.
`body`	object	Parsed JSON request body.
`db`	SafeDb	Bot-scoped database helper (same as the `db` global in normal bot code).
`response`	object	Mutable response descriptor — set fields to control the HTTP response.
`params`	object	Express route parameters (e.g. `{ botId, customPath }`).

// Accessible at:
// POST https://api-prod2-next-bot.nx3r.com/custom/<botId>/notify

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 };
};

If the handler returns a value and response.data has not been set, the return value is used as data automatically.

Response object

Mutate the response object to control what the caller receives:

Field	Type	Description
`statusCode`	number	HTTP status code. Defaults to 200.
`headers`	object	Extra response headers to set (e.g. `{ "X-My-Header": "value" }`).
`message`	string	Short human-readable message included in the JSON response.
`data`	any	Payload returned under the `data` key in the JSON body.

The JSON response body always includes an ok boolean (true when statusCode < 400) plus whatever fields you set on response.

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

Error codes

HTTP status	Cause
400	Invalid `customPath` format, or no handler registered for the requested path.
403	Bot is under halt — requests are rejected until the bot is restarted.
404	Bot ID not found in the platform configuration.
500	Compile error or unhandled exception in the handler. Details are written to `infoCollection` for the bot.

Compile and execution errors appear in the bot's error log inside the NxCreator editor, so you can debug failed webhook calls without needing external logging.

Last updated March 22, 2026

Was this page helpful?