---
title: Bot Management
summary: The Bot Management API allows you to configure ContentGuard, which controls how Fastly responds to bot traffic. Bots are grouped into categories, each of which has a default action. You can override the action for an individual bot within a category.
url: https://www.fastly.com/documentation/reference/api/bot-management
---

The Bot Management API allows you to configure ContentGuard, which controls how Fastly responds to bot traffic. Bots are grouped into categories, each of which has a default action. You can override the action for an individual bot within a category.

## Data model

| Field | Type | Description |
|-------|------|-------------|
| `type` | string | The type of action to apply. |
| `action` | object | The action applied to requests from a single bot. Set the action to 'inherit' to apply the category's action or to a specific value to override the category's action. |
| `bot_id` | string | The unique identifier of the bot. (Read-only) |
| `name` | string | The display name of the bot. (Read-only) |
| `meta` | object | Metadata about the request. |
| `category_id` | string | The unique identifier of the category. (Read-only) |
| `description` | string | A description of the bots the category contains. (Read-only) |
| `detail` | string | An explanation of the problem, specific to this occurrence. |
| `status` | integer | The HTTP status code of the response. |
| `title` | string | A short summary of the problem. |
| `limit` | integer | The <code>limit</code> value used when making the request. |
| `next_cursor` | string | The cursor to use to request the next page of results. Set to <code>null</code> when there are no more results. |
| `total` | integer | The count of results matching the request. |
| `protection_mode` | string | The protection mode of the workspace. <code>off</code> disables all enforcement. <code>log</code> detects and logs bots without blocking or challenging requests. <code>block</code> enforces the actions set on categories and bots. |
| `created_at` | string | The date and time the workspace was created, in RFC 3339 format. (Read-only) |
| `id` | string | A UUID used to uniquely identify the workspace. (Read-only) |
| `services` | array | The IDs of the services attached to this workspace. (Read-only) |
| `updated_at` | string | The date and time the workspace was last updated, in RFC 3339 format. (Read-only) |

## API endpoints

### List workspaces

**GET** `/bot-management/v1/workspaces`

List bot management workspaces.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `cursor` | string | query | No | Cursor for pagination. Use the <code>next_cursor</code> value from a previous response to request the next page of results. |
| `limit` | integer | query | No | Limit how many results are returned. |
| `service_id` | string | query | No | Filter results to the workspace attached to this service. Returns an empty list if the service is not attached to a workspace. |

### Get a workspace

**GET** `/bot-management/v1/workspaces/{workspace_id}`

Retrieve a bot management workspace.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `workspace_id` | string | path | Yes | The ID of the bot management workspace. |

### Update a workspace

**PATCH** `/bot-management/v1/workspaces/{workspace_id}`

Update the attributes of a bot management workspace.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `workspace_id` | string | path | Yes | The ID of the bot management workspace. |

### List categories

**GET** `/bot-management/v1/workspaces/{workspace_id}/policy/categories`

List all bot categories in a workspace's policy. Each category has an action that applies to every bot in the category. To list the bots themselves, use <a href="#bot-management-list-bots">list all bots in a workspace</a> or <a href="#bot-management-list-category-bots">list bots in a category</a>.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `cursor` | string | query | No | Cursor for pagination. Use the <code>next_cursor</code> value from a previous response to request the next page of results. |
| `limit` | integer | query | No | Limit how many results are returned. |
| `workspace_id` | string | path | Yes | The ID of the bot management workspace. |

### Get a category

**GET** `/bot-management/v1/workspaces/{workspace_id}/policy/categories/{category_id}`

Get the attributes of a bot category.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `category_id` | string | path | Yes | The ID of the bot category. |
| `workspace_id` | string | path | Yes | The ID of the bot management workspace. |

### Set a category action

**PATCH** `/bot-management/v1/workspaces/{workspace_id}/policy/categories/{category_id}`

Set the action for a bot category. Every bot in the category configured with the 'inherit' action uses the action set for the category.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `category_id` | string | path | Yes | The ID of the bot category. |
| `workspace_id` | string | path | Yes | The ID of the bot management workspace. |

### List all bots in a workspace

**GET** `/bot-management/v1/workspaces/{workspace_id}/policy/bots`

List all bots in a workspace's policy across all categories.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `cursor` | string | query | No | Cursor for pagination. Use the <code>next_cursor</code> value from a previous response to request the next page of results. |
| `limit` | integer | query | No | Limit how many results are returned. |
| `workspace_id` | string | path | Yes | The ID of the bot management workspace. |

### List bots in a category

**GET** `/bot-management/v1/workspaces/{workspace_id}/policy/categories/{category_id}/bots`

List all bots in a bot category.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `category_id` | string | path | Yes | The ID of the bot category. |
| `cursor` | string | query | No | Cursor for pagination. Use the <code>next_cursor</code> value from a previous response to request the next page of results. |
| `limit` | integer | query | No | Limit how many results are returned. |
| `workspace_id` | string | path | Yes | The ID of the bot management workspace. |

### Get a bot

**GET** `/bot-management/v1/workspaces/{workspace_id}/policy/categories/{category_id}/bots/{bot_id}`

Get the attributes of a bot in a category.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `bot_id` | string | path | Yes | The ID of the bot. |
| `category_id` | string | path | Yes | The ID of the bot category. |
| `workspace_id` | string | path | Yes | The ID of the bot management workspace. |

### Set a bot action

**PATCH** `/bot-management/v1/workspaces/{workspace_id}/policy/categories/{category_id}/bots/{bot_id}`

Set the action for a bot. Set the action to 'inherit' to apply the category's action or to a specific value to override the category's action.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `bot_id` | string | path | Yes | The ID of the bot. |
| `category_id` | string | path | Yes | The ID of the bot category. |
| `workspace_id` | string | path | Yes | The ID of the bot management workspace. |