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.

​

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

​

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 do not have permission to perform this action.
• 404 Not Found: The requested resource could not 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.

​

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:

• View the full list of available endpoints.
• Learn how to manage user permissions through the API.
• Learn how to fetch usage data

​

Resources

• API Reference
• Authorization Guide
• Error handling