> ## Documentation Index
> Fetch the complete documentation index at: https://botpress-ak-docs-20-document-updating-variables-from-outsid.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

export const chatApiPayloadSize = "1 MB";

export const runtimeApiPayloadSize = "1 MB";

export const adminApiPayloadSize = "50 MB";

export const tablesApiPayloadSize = "40 MB";

export const filesApiPayloadSize = "1 MB";

export const webhookPayloadSize = "100 MB";

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](../authentication).
* **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:

```http theme={null}
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`:

```bash theme={null}
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.

```json theme={null}
{
  "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](https://www.npmjs.com/package/@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:

```bash theme={null}
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:

<Note>
  This example uses [`dotenv` ](https://www.npmjs.com/package/dotenv) to manage Botpress credentials. If you'd rather manage your credentials differently, just remove the import and define your token, workspace ID, and bot ID however you like.
</Note>

```ts theme={null}
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](../errors). 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 {adminApiPayloadSize}.

## 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](../authentication)
* [Error handling](../errors)