Neuron Bots API
Bot CRUD, analytics, knowledge base & API key management
Bot CRUD, analytics, knowledge base & API key management
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/neuron-ng:neuron-ng-bots-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Neuron Bots API
version: 1.0.0
description: 'API reference for Neuron — the AI-powered WhatsApp chatbot platform.
Neuron lets you build intelligent chatbots with tool integrations, knowledge bases, and human-in-the-loop monitoring.
## Authentication
Most endpoints require a JWT bearer token obtained from `POST /auth/login`.
Bot API endpoints use API keys prefixed with `nrn_`.
The **Social API** (`/social`) is organization-scoped — authenticate with an **account token** (`nrn_acc_`, from Dashboard → Settings → Account Tokens). Bot API keys are also accepted for backward compatibility but are legacy for this API.
## Response Format
All responses follow the envelope: `{ success: boolean, data?: any, error?: { message, code } }`'
servers:
- url: /api/v1
description: API v1
tags:
- name: Bots
description: Bot CRUD, analytics, knowledge base & API key management
paths:
/bots:
post:
tags:
- Bots
summary: Create a bot
security:
- BearerAuth: []
requestBody:
content:
application/json:
schema:
type: object
required:
- name
- systemPrompt
properties:
name:
type: string
systemPrompt:
type: string
llmModel:
type: string
temperature:
type: number
minimum: 0
maximum: 2
maxTokens:
type: integer
assignment:
type: string
responsibilities:
type: string
greetingMessage:
type: string
welcomeMessage:
type: string
fallbackMessage:
type: string
escalationPrompt:
type: string
required: true
responses:
'201':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
$ref: '#/components/schemas/Bot'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: postBots
x-operation-id-source: derived
get:
tags:
- Bots
summary: List bots for organization
security:
- BearerAuth: []
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: array
items:
$ref: '#/components/schemas/Bot'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: getBots
x-operation-id-source: derived
/bots/{id}:
get:
tags:
- Bots
summary: Get bot details
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
$ref: '#/components/schemas/Bot'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: getBotsById
x-operation-id-source: derived
put:
tags:
- Bots
summary: Update bot
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
systemPrompt:
type: string
llmModel:
type: string
temperature:
type: number
maxTokens:
type: integer
assignment:
type: string
responsibilities:
type: string
greetingMessage:
type: string
welcomeMessage:
type: string
fallbackMessage:
type: string
escalationPrompt:
type: string
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
$ref: '#/components/schemas/Bot'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: putBotsById
x-operation-id-source: derived
delete:
tags:
- Bots
summary: Delete bot
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: deleteBotsById
x-operation-id-source: derived
/bots/{id}/pause:
post:
tags:
- Bots
summary: Pause bot (stops AI auto-replies; Bot API sends still work)
description: Pausing a bot stops it from auto-responding to incoming WhatsApp messages. Messages are still saved but the AI will not reply. Outbound Bot API calls (/send, /compose, /conversations/:id/send) continue to work normally. Playground and widget conversations are also unaffected.
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: postBotsByIdPause
x-operation-id-source: derived
/bots/{id}/resume:
post:
tags:
- Bots
summary: Resume bot (re-enables AI auto-replies)
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: postBotsByIdResume
x-operation-id-source: derived
/bots/{id}/analytics:
get:
tags:
- Bots
summary: Get bot analytics
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: getBotsByIdAnalytics
x-operation-id-source: derived
/bots/{id}/knowledge-bases:
post:
tags:
- Bots
summary: Attach knowledge base to bot
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
requestBody:
content:
application/json:
schema:
type: object
required:
- knowledgeBaseId
properties:
knowledgeBaseId:
type: string
format: uuid
required: true
responses:
'201':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: postBotsByIdKnowledgeBases
x-operation-id-source: derived
get:
tags:
- Bots
summary: List knowledge bases for bot
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: array
items:
$ref: '#/components/schemas/KnowledgeBase'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: getBotsByIdKnowledgeBases
x-operation-id-source: derived
/bots/{id}/knowledge-bases/{kbId}:
delete:
tags:
- Bots
summary: Detach knowledge base from bot
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
- name: kbId
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: deleteBotsByIdKnowledgeBasesByKbId
x-operation-id-source: derived
/bots/{id}/api-keys:
post:
tags:
- Bots
summary: Create API key for bot
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
expiresAt:
type: string
format: date-time
required: true
responses:
'201':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
key:
type: string
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: postBotsByIdApiKeys
x-operation-id-source: derived
get:
tags:
- Bots
summary: List API keys for bot
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: array
items:
type: object
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: getBotsByIdApiKeys
x-operation-id-source: derived
/bots/{id}/api-keys/{keyId}:
delete:
tags:
- Bots
summary: Revoke API key
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
- name: keyId
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: deleteBotsByIdApiKeysByKeyId
x-operation-id-source: derived
/bots/{id}/channels:
get:
tags:
- Bots
summary: List channels connected to bot
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: array
items:
type: object
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: getBotsByIdChannels
x-operation-id-source: derived
post:
tags:
- Bots
summary: Add secondary channel to bot
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
requestBody:
content:
application/json:
schema:
type: object
required:
- channelId
properties:
channelId:
type: string
format: uuid
required: true
responses:
'201':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: postBotsByIdChannels
x-operation-id-source: derived
/bots/{id}/channels/{channelId}:
delete:
tags:
- Bots
summary: Remove channel from bot
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
- name: channelId
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: deleteBotsByIdChannelsByChannelId
x-operation-id-source: derived
/bots/{id}/channels/{channelId}/silent-mode:
patch:
tags:
- Bots
summary: Toggle silent mode for a bot channel
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
- name: channelId
in: path
required: true
schema:
type: string
format: uuid
description: ''
requestBody:
content:
application/json:
schema:
type: object
required:
- silentMode
properties:
silentMode:
type: boolean
description: When true, bot processes messages but does not send WhatsApp replies
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: patchBotsByIdChannelsByChannelIdSilentMode
x-operation-id-source: derived
components:
schemas:
KnowledgeBase:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
description:
type: string
rootInstruction:
type: string
orgId:
type: string
format: uuid
createdAt:
type: string
format: date-time
ErrorResponse:
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
message:
type: string
code:
type: string
Bot:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
systemPrompt:
type: string
llmModel:
type: string
temperature:
type: number
maxTokens:
type: integer
isActive:
type: boolean
orgId:
type: string
format: uuid
assignment:
type: string
responsibilities:
type: string
greetingMessage:
type: string
welcomeMessage:
type: string
fallbackMessage:
type: string
escalationPrompt:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT access token from POST /auth/login
ApiKeyAuth:
type: http
scheme: bearer
description: Bot API key (nrn_xxx) from bot API keys management
AccountTokenAuth:
type: http
scheme: bearer
description: Account token (nrn_acc_xxx) from Dashboard > Settings > Account Tokens