Docs

Getting started

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 dotenv from 'dotenv'
import { Client } from '@botpress/client'

dotenv.config()

async function main() {
  const token = process.env.TOKEN
  const workspaceId = process.env.WORKSPACE_ID
  const botId = process.env.BOT_ID

  if (!botId) {
    throw new Error('Missing required BOT_ID environment variable')
  }

  console.log(token, workspaceId, botId)

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

  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 50 MB.

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