The Admin API allows administrators to manage users, settings, and logs within the platform. This guide will help you quickly get up and running with the API.

​
Prerequisites

Before using the Admin API, make sure you have the following:
  • Token: You must generate a token to authenticate your requests. The details for obtaining and using your token are explained in our Authorization Guide.
  • Workspace ID: Each API request requires the x-workspace-id header to specify the workspace you’re operating on. Ensure you have the correct workspace ID.
All API requests will be made to endpoints under this URL.

​
Two Ways to Interact with the API

There are two ways to interact with the Admin API: using HTTP requests or the Botpress client. Choose the one that fits your needs.

​
Option 1: Using HTTP Requests

You can interact with the Admin API directly through HTTP requests. The base URL for the Admin API is: 
https://api.botpress.cloud/v1/admin
All API requests will be made to endpoints under this URL. You must include your token in the Authorization header as a Bearer token. In addition to the token, you will have to include the x-workspace-id header in each API request. This header specifies the workspace that the request is for. Here’s an example of how to fetch a list of bots:

​
Example: Fetching bots

To fetch a list of bots, send a GET request to /bots. Here’s an example using curl: 
curl -X GET "https://api.botpress.cloud/v1/admin/bots" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"
This will return a JSON object containing a list of bots. 
{
  "bots": [
    {
      "id": "string",
      "createdAt": "2025-04-03T19:25:44.810Z",
      "updatedAt": "2025-04-03T19:25:44.810Z",
      "name": "string",
      "deployedAt": "2025-04-03T19:25:44.810Z"
    }
  ],
  "meta": {
    "nextToken": "string"
  }
}

​
Option 2: Using the Botpress Client

Alternatively, you can use the Botpress client to interact with the Admin API programmatically. This is ideal for integrating the Admin API within your application.

​
Installation

To install the Botpress client: 
npm install @botpress/client

​
Example: Fetching Workspaces with the Client

After installing the client, you can instantiate it with your token and workspace ID, then use it to fetch a bot: 
import { admin } from '@botpress/client'

const token = process.env.TOKEN
const workspaceID = process.env.WORKSPACE_ID
const botId = process.env.BOT_ID

const client = new admin.Client({
  token,
  workspaceId,
})

async function main() {
  const { bot } = await client.getBot({ id: botId })
  console.log('### bot', bot)
}

void main()

​
Error Handling

In case of errors, the API will return an appropriate HTTP status code and an error message. Here are some common errors you might encounter, and why:
  • 401 Unauthorized: Your token and/or x-workspace-id is missing or invalid.
  • 403 Forbidden: You don’t have permission to perform this action.
  • 404 Not Found: The requested resource couldn’t be found.
  • 500 Internal Server Error: Something went wrong on the server side.

​
Example: Handling a 401 Unauthorized Error

If you receive a 401 Unauthorized error, check that your token is valid and included in the Authorization header of your request, and that the correct x-workspace-id is provided.

​
Quotas/limits

The maximum payload size for the Admin API is .

​
Next Steps

Now that you’ve successfully made your first request, you can explore other API endpoints and features. Here are a few things you can do next:

​
Resources