Skip to content
Cloudflare Docs
Docs DirectoryAPIsSDKs

Configure Schema validation via the API

Schema validation 2.0 allows all corresponding configuration calls to be made via API. This validation centers more around individual endpoints and lets you set mitigation actions for each endpoint individually. Additionally, you can use Cloudflare-provided learned schemas that we learn automatically from your traffic for individual endpoints.

Upload schemas via the API to Schema validation

  1. Upload a schema.
  2. Ensure that your endpoints are added in Endpoint Management.
  3. Set the schema to active if it is not already done.
  4. Set the Schema validation zone-wide action from none to log.
  5. Send test traffic that violates the schema.
  6. View test traffic in Security Events by filtering for Service > API Shield - Schema validation.
  7. Optional:
    • Set a single endpoint to block.
    • Set the Schema validation zone-wide to block.
    • Temporarily override all schemas zone-wide to none.
    • Remove the temporary override.

Cloudflare recommends you to rerun test traffic and monitor the HTTP response codes after changing any settings to ensure Schema validation is operating as expected.

Settings changes may take a few minutes to implement.

Configuration

Upload and activate a schema

Upload a schema via the v4 API using POST. This example requires a example_schema.yaml schema file in the current folder.

Required API token permissions

 At least one of the following token permissions is required:
  • Account API Gateway
  • Domain API Gateway
Upload a schema
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, Schema validation is disabled for an uploaded schema so that you can inspect it first. You can upload a schema and enable it immediately by setting the form parameter validation_enabled=true.

Use a PATCH request to activate a schema after inspection.

Required API token permissions

 At least one of the following token permissions is required:
  • Account API Gateway
  • Domain API Gateway
Enable validation for a schema
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
  }'