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.
This API configures ContentGuard. It is not the bot detection and rule feature set of the Next-Gen WAF API, which is documented separately.
Workspaces
A workspace is the container for bot management settings and policy. To find the workspace attached to a service, filter the list workspaces endpoint by service_id.
Policy, categories, and bots
Policy is the enforcement layer within a workspace. It contains categories, and each category contains bots:
- Setting an action on a category applies that action to every bot in the category, including bots that Fastly adds to the category later.
- Setting an action on a bot overrides the action of the category it belongs to. Set a bot's action to
inheritto return it to the category action.
Categories and bots are both defined by Fastly. You cannot create or delete them, only change their actions.
Protection mode
Each workspace has a protection_mode that gates all enforcement:
off: no enforcement, regardless of category and bot actions.log: bots are detected and logged, but no requests are blocked or challenged.block: category and bot actions are fully enforced.
Data model
The action applied to matching requests.
type | string | The type of action to apply. Required. | |
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 limit value used when making the request. | |
next_cursor | string | The cursor to use to request the next page of results. Set to null when there are no more results. | |
total | integer | The count of results matching the request. | |
protection_mode | string | The protection mode of the workspace. off disables all enforcement. log detects and logs bots without blocking or challenging requests. block 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. |
Endpoints
GET/bot-management/v1/workspaces/workspace_id/policy/categories/category_id/bots
