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 generated from the project's Shield crawler policies. This is what Shield serves for apps that have NO robots.txt of their own. An app that ships one has it served verbatim with these crawler rules appended instead, so this is not necessarily the file a crawler receives. You do not need to copy this into your project.

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