---
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 that is set to <code>inherit</code>. 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 default action for a bot category. Bots set to <code>inherit</code> follow this action. Bots with their own action keep it. To remove every bot's own action in the category, use <a href="#bot-management-update-category-bots">set the action for all bots in a category</a>.

**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. |

### Set the action for all bots in a category

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

Set the action for every bot in a category. Setting <code>inherit</code> removes each bot's own action, so every bot follows the category's action. The category's own action is unchanged. The update applies to every bot in the category or to none, and repeating it gives the same result. The response lists every bot in the category, including bots that already inherited, and is not paginated.

**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. |

### 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. |

