Shield API

AI crawler control — policies, analytics, robots.txt

REST API endpoints for Shield. 12 operations.

Get Shield config

plaintext

GET /v1/shield/config

Returns the Shield configuration (default action, challenge settings) for the caller's project.

Auth: Bearer API key

Responses

Status	Description
`200`	Shield configuration for the caller's project
`401`	Missing or invalid credentials
`403`	Token lacks the waf:read scope or is not project-scoped
`500`	Internal error

operationId: getShieldConfig

Update Shield config

plaintext

PUT /v1/shield/config

Replaces the Shield configuration for the caller's project. Requires the Pro plan or higher.

Auth: Bearer API key

Request body

application/json (required) — schema ScopeConfig.

Responses

Status	Description
`200`	Updated shield configuration
`401`	Missing or invalid credentials
`403`	Requires Pro plan, the waf:write scope, or a project-scoped token
`500`	Internal error

operationId: updateShieldConfig

List Shield crawlers

plaintext

GET /v1/shield/crawlers

Returns the known AI crawlers with their per-project policy and traffic stats, plus any custom user-defined crawler rules.

Auth: Bearer API key

Responses

Status	Description
`200`	Known crawlers (with per-scope policy + stats) and custom rules
`401`	Missing or invalid credentials
`403`	Token lacks the waf:read scope or is not project-scoped
`500`	Internal error

operationId: listShieldCrawlers

Set a crawler's verification IP ranges

plaintext

PUT /v1/shield/crawlers/{id}/ip-ranges

Sets the IP addresses or CIDR ranges used to verify a crawler's source IP. Requires the Pro plan or higher.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Crawler id (e.g. `gptbot`)

Request body

application/json (required) — schema IpRangesRequest.

Responses

Status	Description
`200`	IP ranges set for the crawler
`400`	Invalid IP or CIDR
`401`	Missing or invalid credentials
`403`	Requires Pro plan, the waf:write scope, or a project-scoped token
`404`	Unknown crawler
`500`	Internal error

operationId: setShieldCrawlerIpRanges

Clear a crawler policy

plaintext

DELETE /v1/shield/crawlers/{id}/policy

Removes the access policy for a crawler, reverting it to the project default. Policy controls require the Pro plan or higher.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Crawler id (e.g. `gptbot`)

Responses

Status	Description
`200`	Policy cleared
`401`	Missing or invalid credentials
`403`	Requires Pro plan, the waf:write scope, or a project-scoped token
`404`	No policy set for crawler
`500`	Internal error

operationId: clearShieldCrawlerPolicy

Set a crawler policy

plaintext

PUT /v1/shield/crawlers/{id}/policy

Sets the access policy (allow / block / rate-limit) for a known crawler in the caller's project. Policy controls require the Pro plan or higher.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Crawler id (e.g. `gptbot`)

Request body

application/json (required) — schema CrawlerPolicy.

Responses

Status	Description
`200`	Policy set for the crawler
`401`	Missing or invalid credentials
`403`	Requires Pro plan, the waf:write scope, or a project-scoped token
`404`	Unknown crawler
`500`	Internal error

operationId: setShieldCrawlerPolicy

Create a custom Shield rule

plaintext

POST /v1/shield/custom

Adds a customer-defined crawler rule matched by User-Agent substring, with its own access policy. Requires the Pro plan or higher.

Auth: Bearer API key

Request body

application/json (required) — schema CustomRuleRequest.

Responses

Status	Description
`200`	Custom rule created
`400`	Invalid rule
`401`	Missing or invalid credentials
`403`	Requires Pro plan, the waf:write scope, or a project-scoped token
`500`	Internal error

operationId: createShieldCustomRule

Delete a custom Shield rule

plaintext

DELETE /v1/shield/custom/{id}

Removes a custom crawler rule by id. Requires the Pro plan or higher.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Custom rule id (UUID)

Responses

Status	Description
`200`	Custom rule deleted
`401`	Missing or invalid credentials
`403`	Requires Pro plan, the waf:write scope, or a project-scoped token
`404`	Custom rule not found
`500`	Internal error

operationId: deleteShieldCustomRule

Update a custom Shield rule

plaintext

PUT /v1/shield/custom/{id}

Updates the access policy of an existing custom crawler rule. Requires the Pro plan or higher.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Custom rule id (UUID)

Request body

application/json (required) — schema CrawlerPolicy.

Responses

Status	Description
`200`	Custom rule policy updated
`401`	Missing or invalid credentials
`403`	Requires Pro plan, the waf:write scope, or a project-scoped token
`404`	Custom rule not found
`500`	Internal error

operationId: updateShieldCustomRule

List Shield events

plaintext

GET /v1/shield/events

Returns recent Shield crawler events for the project, paginated.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`cursor`	query	`string`	No	Opaque keyset cursor (preferred); returns {data, has_more, next_cursor}
`page`	query	`integer`	No	Zero-based page index (legacy offset mode; ignored when cursor is set)
`limit`	query	`integer`	No	Page size (default 50, max 200)

Responses

Status	Description
`200`	Recent shield events for the project (paginated)
`401`	Missing or invalid credentials
`403`	Token lacks the waf:read scope or is not project-scoped
`500`	Internal error

operationId: listShieldEvents

Generate robots.txt

plaintext

GET /v1/shield/robots-txt

Returns a robots.txt file generated from the project's Shield crawler policies.

Auth: Bearer API key

Responses

Status	Description
`200`	Generated robots.txt for the project
`401`	Missing or invalid credentials
`403`	Token lacks the waf:read scope or is not project-scoped
`500`	Internal error

operationId: getShieldRobotsTxt

Get Shield statistics

plaintext

GET /v1/shield/stats

Returns aggregate request, block, and rate-limit counts broken down by crawler for the caller's project.

Auth: Bearer API key

Responses

Status	Description
`200`	Aggregate request/block/rate-limit counts, by crawler
`401`	Missing or invalid credentials
`403`	Token lacks the waf:read scope or is not project-scoped
`500`	Internal error

operationId: getShieldStats