Botpress API
Agent
Version 2 |Builder External API Referencev2
Swagger style interactive documentation for listing bots, inspecting bot integrations, and retrieving conversation messages.
Servers
https://backend.versalence.online/api/v2/agent-builder/ext
Security: Never paste API keys or webhook secrets into a published Bookshelf page. Live testing is available in the standalone API reference, subject to CORS permissions.
Bot Operations
GET/workspaces/{workspaceId}/botsList Bots
List the bots registered in the selected workspace, including build type and timestamps.
Path parameters
workspaceId
string
Yes
Workspace identifier
Responses
200 Successful response · application/json
{
"success": "boolean",
"data": [
{
"id": "string (UUID)",
"name": "string",
"buildType": "string",
"createdAt": "string (date-time)",
"updatedAt": "string (date-time)"
}
],
"partial": "boolean"
}
Example response
{
"success": true,
"data": [
{
"id": "29b31b9e-39a6-4bac-8a0c-ea5c1e9d3fc8",
"name": "Desk",
"buildType": "Workflow",
"createdAt": "2026-10-14T17:01:54.818Z",
"updatedAt": "2026-10-14T17:01:55.876Z"
},
{
"id": "87884a25-71da-4c2d-ae95-5013bd4480ab",
"name": "Empty Bot",
"buildType": "Workflow",
"createdAt": "2026-10-14T17:01:56.945Z",
"updatedAt": "2026-10-14T17:01:57.722Z"
},
{
"id": "4fad64bd-0254-46a5-afdf-cdcae98c85b5",
"name": "National Industries",
"buildType": "Workflow",
"createdAt": "2026-10-15T17:47:13.259Z",
"updatedAt": "2026-10-23T14:31:09.036Z"
},
{
"id": "9e451f63-f9c2-4e46-9b92-005738f2ccb5",
"name": "Sewa Enterprises",
"buildType": "Workflow",
"createdAt": "2026-10-16T07:58:01.480Z",
"updatedAt": "2026-10-23T11:55:55.059Z"
},
{
"id": "a2986485-befd-4a71-a05a-3942e58b57e8",
"name": "Exotica Steel",
"buildType": "Workflow",
"createdAt": "2026-10-16T13:07:16.893Z",
"updatedAt": "2026-10-23T11:48:36.887Z"
},
{
"id": "e9debc74-5c1e-4204-b497-49bba1fc5e25",
"name": "Herbaveda Overseas",
"buildType": "Workflow",
"createdAt": "2026-10-16T13:08:39.757Z",
"updatedAt": "2026-10-23T11:52:34.675Z"
},
{
"id": "cc4ec02f-54f9-4639-b7e9-e20ce6a7bfc9",
"name": "Unicorn Equipment",
"buildType": "Workflow",
"createdAt": "2026-10-16T13:24:08.863Z",
"updatedAt": "2026-10-23T11:57:31.259Z"
},
{
"id": "314aa3eb-0136-4ebb-a709-b3d5d598375a",
"name": "Jay Shree Machine Tools",
"buildType": "Workflow",
"createdAt": "2026-10-17T04:47:37.910Z",
"updatedAt": "2026-10-19T15:37:44.557Z"
}
],
"partial": false
}
GET/workspaces/{workspaceId}/bots/{botId}/credentialsGet Bot Integrations
Fetch integration status and webhook configuration for the requested bot. Treat the response as sensitive because it can contain a webhook secret.
Path parameters
workspaceId
string
Yes
Workspace identifier
botId
UUID
Yes
Bot identifier
Responses
200 Successful response · application/json
{
"success": "boolean",
"data": {
"botId": "string (UUID)",
"name": "string",
"enabled": "boolean",
"workspaceId": "string",
"webhook": {
"integrationId": "string",
"enabled": "boolean",
"webhookId": "string (UUID)",
"secret": "string (sensitive)"
}
}
}
Example response
{
"success": true,
"data": {
"botId": "4fad64bd-0254-46a5-afdf-cdcae98c85b5",
"name": "National Industries",
"enabled": true,
"workspaceId": "wkspace_01M4XM03S725556S8YM712H1W0",
"webhook": {
"integrationId": "intver_01KVC0MXH1NRBX66RQ9CR7Z14E",
"enabled": true,
"webhookId": "a05ffe7b-4c0a-4b27-acc5-de6d209ff6f7",
"secret": "REDACTED"
}
}
}
GET/workspaces/{workspaceId}/bots/{botId}/conversations/{conversationId}/messagesGet Chats by conversation_id
Return conversation messages, including text and choice payloads, direction, timestamps and optional pagination token. The illustrated response is ordered newest first; sort by createdAt to reconstruct the conversation chronologically.
Path parameters
workspaceId
string
Yes
Workspace identifier
botId
UUID
Yes
Bot identifier
conversationId
string
Yes
Conversation identifier
Responses
200 Successful response · application/json
{
"success": "boolean",
"data": [
{
"id": "string (UUID)",
"createdAt": "string (date-time)",
"updatedAt": "string (date-time)",
"conversationId": "string",
"payload": {
"type": "text | choice",
"text": "string",
"options": "array<{label:string,value:string}> (optional)"
},
"tags": "object",
"userId": "string",
"type": "text | choice",
"direction": "incoming | outgoing"
}
],
"nextToken": "string | null"
}
Example response
{
"success": true,
"data": [
{
"id": "c916f588-5fc3-4954-b32a-54ad215c60a9",
"createdAt": "2026-10-22T11:03:22.793Z",
"updatedAt": "2026-10-22T11:03:22.793Z",
"conversationId": "conv_01M5HM3R4N9VTXTDSK55H7JRVG",
"payload": {
"type": "text",
"text": "This session has ended after 5 minutes of inactivity. You can message us again whenever you are ready."
},
"tags": {
"iteration": "",
"origin": "workflow://wf-timeout/node/nd-e6c012a652/card/ins-e1f8c437b3"
},
"userId": "user_01M50ATG6S5X341FZGP8B48FBV",
"type": "text",
"direction": "outgoing"
},
{
"id": "67a86a7d-3b2a-4a69-b42d-170e5e5be750",
"createdAt": "2026-10-22T10:58:18.453Z",
"updatedAt": "2026-10-22T10:58:18.453Z",
"conversationId": "conv_01M5HM3R4N9VTXTDSK55H7JRVG",
"payload": {
"type": "choice",
"text": "To help you further, could you tell me the shredding type you need? For example: cross cut, strip cut, or micro cut.",
"options": [
{
"label": "Cross cut",
"value": "Cross cut"
},
{
"label": "Strip cut",
"value": "Strip cut"
},
{
"label": "Micro cut",
"value": "Micro cut"
},
{
"label": "Other (type below)",
"value": "Other (type below)"
}
]
},
"tags": {
"iteration": "",
"origin": "LLMZ"
},
"userId": "user_01M50ATG6S5X341FZGP8B48FBV",
"type": "choice",
"direction": "outgoing"
},
{
"id": "89460308-2d7a-4efe-add6-a5f1ece48d5a",
"createdAt": "2026-10-22T10:58:17.290Z",
"updatedAt": "2026-10-22T10:58:17.290Z",
"conversationId": "conv_01M5HM3R4N9VTXTDSK55H7JRVG",
"payload": {
"type": "text",
"text": "The starting price for office use paper shredders is **₹12,000 per unit**. Other models are available at ₹16,500, ₹18,000, ₹32,000, and up to ₹35,000 per piece for higher-capacity machines. These are indicative prices; the team will confirm the final price based on your exact requirement."
},
"tags": {
"iteration": "",
"origin": "LLMZ"
},
"userId": "user_01M50ATG6S5X341FZGP8B48FBV",
"type": "text",
"direction": "outgoing"
},
{
"id": "547febde-e8a3-4c35-ae7e-83230a9a635b",
"createdAt": "2026-10-22T10:58:10.189Z",
"updatedAt": "2026-10-22T10:58:10.189Z",
"conversationId": "conv_01M5HM3R4N9VTXTDSK55H7JRVG",
"payload": {
"text": "prices kya hain inke?",
"type": "text"
},
"tags": {},
"userId": "user_01M5HM3QTXSXZ0SJXXBAQWQS00",
"type": "text",
"direction": "incoming"
},
{
"id": "f92cf6b7-bb6b-4974-8ab4-c1a4d1acb32f",
"createdAt": "2026-10-22T10:57:22.070Z",
"updatedAt": "2026-10-22T10:57:22.070Z",
"conversationId": "conv_01M5HM3R4N9VTXTDSK55H7JRVG",
"payload": {
"type": "choice",
"text": "To help you choose the right office shredder, could you tell me the shredding type you need?",
"options": [
{
"label": "Cross Cut",
"value": "Cross Cut"
},
{
"label": "Micro Cut",
"value": "Micro Cut"
},
{
"label": "Other (type below)",
"value": "Other"
}
]
},
"tags": {
"iteration": "",
"origin": "LLMZ"
},
"userId": "user_01M50ATG6S5X341FZGP8B48FBV",
"type": "choice",
"direction": "outgoing"
},
{
"id": "e4010052-2c2e-425e-9c26-7037ed914448",
"createdAt": "2026-10-22T10:57:15.389Z",
"updatedAt": "2026-10-22T10:57:15.389Z",
"conversationId": "conv_01M5HM3R4N9VTXTDSK55H7JRVG",
"payload": {
"type": "choice",
"text": "Please select the category you are interested in:",
"options": [
{
"label": "Glue Binding Machine",
"value": "Glue Binding Machine"
},
{
"label": "Comb Binding Machines",
"value": "Comb Binding Machines"
},
{
"label": "Spiral Binding Machines",
"value": "Spiral Binding Machines"
},
{
"label": "Corner Cutter Machine",
"value": "Corner Cutter Machine"
},
{
"label": "Currency Counting Machines",
"value": "Currency Counting Machines"
},
{
"label": "Safety Locker",
"value": "Safety Locker"
},
{
"label": "Notebook Making Machines",
"value": "Notebook Making Machines"
},
{
"label": "Plastic Spirals",
"value": "Plastic Spirals"
},
{
"label": "Wiro Ring Wire And Plastic Comb Spico",
"value": "Wiro Ring Wire And Plastic Comb Spico"
},
{
"label": "Creasing Machine",
"value": "Creasing Machine"
},
{
"label": "Pouch Laminator",
"value": "Pouch Laminator"
},
{
"label": "Corner Taping Machine",
"value": "Corner Taping Machine"
},
{
"label": "Plotter Paper Rolls",
"value": "Plotter Paper Rolls"
},
{
"label": "Other (type below)",
"value": "Other (type below)"
}
]
},
"tags": {
"iteration": "",
"origin": "LLMZ"
},
"userId": "user_01M50ATG6S5X341FZGP8B48FBV",
"type": "choice",
"direction": "outgoing"
},
{
"id": "d3704492-5ba0-4d65-8bca-ff5798b4c035",
"createdAt": "2026-10-22T10:57:11.853Z",
"updatedAt": "2026-10-22T10:57:11.853Z",
"conversationId": "conv_01M5HM3R4N9VTXTDSK55H7JRVG",
"payload": {
"text": "office shredder chahiye tha",
"type": "text"
},
"tags": {},
"userId": "user_01M5HM3QTXSXZ0SJXXBAQWQS00",
"type": "text",
"direction": "incoming"
}
],
"nextToken": null
}
Authentication & examples
All endpoints require x-api-key in the request header. The base URL and documented paths combine as follows:
curl --request GET \
--url 'https://backend.versalence.online/api/v2/agent-builder/ext/workspaces/{workspaceId}/bots' \
--header 'x-api-key: YOUR_API_KEY'
Data model notes
success
Boolean indicating application level success
data
Endpoint result; array for bots and messages, object for integrations
partial
List bots response field indicating partial result in the supplied example
nextToken
Message pagination token; null in the supplied example. Its request parameter format is not documented in the supplied samples.
payload
May be text or a choice object with labeled options
direction
incoming or outgoing
Only HTTP 200 response bodies were provided. Error statuses, pagination request semantics, scopes, limits, and other integrations are not asserted here.
Select an endpoint to test.