API configuration

Use the API to upload, activate, list, and delete OpenAPI schemas. An uploaded schema supplies a Schema Profile for its operations.

Configure an uploaded schema

Upload a schema.
Add the schema operations to the Web Assets inventory.
Activate the schema to make uploaded profile evaluation available.
Send representative traffic through the configured operations.
Analyze cf.schema_validation.uploaded.violated in Profile Analysis.
Configure mitigation with WAF Custom Rules.

Settings changes may take a few minutes to implement.

Configuration

Upload and activate a schema

Upload a schema with POST. This example uses example_schema.yaml from the current directory.

Required API token permissions

At least one of the following token permissions is required:

Account API Gateway
Domain API Gateway

Upload a schemabash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/schema_validation/schemas" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"kind": "openapi_v3",
		"name": "example_schema",
		"source": "<SOURCE>",
		"validation_enabled": true
	}'

{
	"result": {
		"schema": {
			"schema_id": "af632e95-c986-4738-a67d-2ac09995017a",
			"name": "example_schema",
			"kind": "openapi_v3",
			"source": "<SOURCE>",
			"created_at": "2023-04-03T15:10:08.902309Z"
		}
	},
	"success": true,
	"errors": [],
	"messages": []
}

By default, uploaded schema evaluation is inactive. Set validation_enabled=true to make evaluation available during upload.

Use PATCH to activate evaluation after inspecting the schema.

Required API token permissions

At least one of the following token permissions is required:

Account API Gateway
Domain API Gateway

Enable validation for a schemabash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/api_gateway/user_schemas/$SCHEMA_ID" \
	--request PATCH \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"validation_enabled": true
	}'

{
	"result": {
		"schema_id": "0bf58160-5da3-48ac-80a9-069f9642c1a0",
		"name": "api_schema.json",
		"kind": "openapi_v3",
		"validation_enabled": true,
		"created_at": "0001-01-01T00:00:00Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

Activation makes uploaded profile evaluation available for configured operations. It does not configure mitigation.

Add schema operations

Schemas contain hosts, paths, and methods that define operations. An operation represents an endpoint by HTTP method, hostname pattern, and path pattern.

Schema Validation evaluates requests only for operations added to Web Assets. Retrieve schema operations and their configuration with GET.

cURL commandbash

curl --request GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/user_schemas/{schema_id}/operations?feature=schema_info&operation_status=new&page=1&per_page=5000" \
--header "Authorization: Bearer <API_TOKEN>" \
--header 'Content-Type: application/json'

{
	"result": [
		{
			"method": "GET",
			"host": "example.com",
			"endpoint": "/pets"
		}
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"page": 1,
		"per_page": 30,
		"count": 1,
		"total_count": 1
	}
}

To receive information about the configuration of existing operations, Cloudflare recommends passing the ?feature=schema_info parameter.

Add schema operations to Web Assets with POST.

cURL commandbash

curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations" \
--header "Authorization: Bearer <API_TOKEN>" \
--header 'Content-Type: application/json' \
--data '[
  {
   "method": "GET",
   "host": "example.com",
   "endpoint": "/pets",
  }
]'

{
	"result": [
		{
			"operation_id": "6c734fcd-455d-4040-9eaa-dbb3830526ae",
			"method": "GET",
			"host": "example.com",
			"endpoint": "/pets",
			"last_updated": "2023-04-04T16:07:37.575971Z"
		}
	],
	"success": true,
	"errors": [],
	"messages": []
}

You can add schema operations that do not exist in Web Assets. This API call supports up to 20 operations and requires jq. For schemas with more than 20 new operations, run the command again to add the next batch.

cURL commandbash

response="$(curl --silent --fail-with-body "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/user_schemas/{schema_id}/operations?feature=schema_info&page=1&per_page=20&operation_status=new" --header "Authorization: Bearer <API_TOKEN>")" || exit 1
operations="$(printf "%s" "$response" | jq --exit-status ".result")" || exit 1

if [ "$(printf "%s" "$operations" | jq "length")" -eq 0 ]; then
	printf "No new operations found.\n"
else
	curl --silent --fail-with-body "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations" \
	--header "Authorization: Bearer <API_TOKEN>" \
	--header "Content-Type: application/json" \
	--data "$operations" || exit 1
fi

List all schemas

List uploaded schemas on a zone with GET.

validation_enabled=true is an optional parameter.

Required API token permissions

At least one of the following token permissions is required:

Account API Gateway
Account API Gateway Read
Domain API Gateway
Domain API Gateway Read

List all uploaded schemasbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/schema_validation/schemas" \
	--request GET \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

{
    "result":  [
        {
	        "schema_id": "af632e95-c986-4738-a67d-2ac09995017a",
	        "name": "example_schema",
	        "kind": "openapi_v3",
	        "source": "<SOURCE>",
	        "created_at": "2023-04-03T15:10:08.902309Z"
	    }
    ]
    "success": true,
    "errors":
    [],
    "messages":
    []
}

Delete a schema

You can delete a schema using DELETE.

Required API token permissions

At least one of the following token permissions is required:

Account API Gateway
Domain API Gateway

Delete a schemabash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/schema_validation/schemas/$SCHEMA_ID" \
	--request DELETE \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

{
	"result": null,
	"success": true,
	"errors": [],
	"messages": []
}