REST API

Use the AI Search REST API to manage namespaces over HTTP.

Authentication

All requests require an API token with AI Search:Edit and AI Search:Run permissions.

In the Cloudflare dashboard, go to My Profile > API Tokens.
Go to API Tokens ↗
Select Create Token.
Select Create Custom Token.
Enter a Token name, for example AI Search Manager.
Under Permissions, add two permissions:
- Account > AI Search:Edit
- Account > AI Search:Run
Select Continue to summary, then select Create Token.
Copy and save the token value. This is your API_TOKEN.

Include the token in the Authorization header for all requests:

Authorization: Bearer <API_TOKEN>

API paths

Path	Description
`/accounts/{account_id}/ai-search/namespaces`	Lists and creates namespaces
`/accounts/{account_id}/ai-search/namespaces/{name}`	Operates on a single namespace

For the full specification, refer to the Namespace API reference.

Operations

Operation	Method	Description
Create	`POST`	Create a namespace
List	`GET`	List namespaces
Get	`GET`	Get a namespace by name
Update	`PUT`	Update the description or public endpoint
Delete	`DELETE`	Delete an empty namespace
Move instance	`PATCH`	Move an instance to a different namespace

To search across several instances in a namespace, refer to Multi-Instance Search and Multi-Instance Chat Completions in the API reference.

Fields

Use these fields in the request body when you create or update a namespace.

Field	Type	Create	Update	Description
`name`	string	Required	-	The namespace name. Use 1 to 28 lowercase letters, digits, and hyphens. The name must start and end with a letter or digit. You cannot rename a namespace.
`description`	string	Optional	Optional	A description of up to 256 characters. Set it to `null` to clear it.
`public_endpoint_params`	object	Optional	Optional	The namespace public endpoint configuration. Refer to Namespace public endpoints.

On update, fields you omit keep their current value. Set public_endpoint_params to null to remove the public endpoint configuration.

You cannot change the description of the default namespace. You can configure its public endpoint.

Examples

Create a namespace

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support",
    "description": "Customer support content"
  }'

An account can have up to 100 namespaces. Creating more returns error 7062 (max_namespaces_reached).

List namespaces

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces?per_page=50" \
  -H "Authorization: Bearer <API_TOKEN>"

Query parameter	Description
`page`	The page number to return. Defaults to `1`.
`per_page`	The number of namespaces per page. Defaults to `20`. Maximum `100`.
`search`	Return namespaces whose name or description contains this string. Case-insensitive.

Update a namespace

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/support" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Support articles and FAQs"
  }'

Delete a namespace

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/support" \
  -H "Authorization: Bearer <API_TOKEN>"

A namespace must be empty before you delete it. If it still contains instances, the request returns error 7066 (namespace_not_empty). Move or delete the instances first. Instances that are still being deleted do not block the request.

You cannot delete the default namespace. The request returns error 7065 (cannot_modify_default_namespace).

Move an instance

Move an instance to another namespace with a PATCH request on the instance in its current namespace:

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/default/instances/docs" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "new_namespace": "support"
  }'

The target namespace cannot already contain an instance with the same name.

Errors

For namespace error codes, refer to API error codes.