# User Schemas ## Retrieve information about all schemas on a zone `client.apiGateway.userSchemas.list(UserSchemaListParamsparams, RequestOptionsoptions?): V4PagePaginationArray` **get** `/zones/{zone_id}/api_gateway/user_schemas` Lists all OpenAPI schemas uploaded to API Shield for the zone, including their validation status and associated operations. ### Parameters - `params: UserSchemaListParams` - `zone_id: string` Path param: Identifier. - `omit_source?: boolean` Query param: Omit the source-files of schemas and only retrieve their meta-data. - `page?: number` Query param: Page number of paginated results. - `per_page?: number` Query param: Maximum number of results per page. - `validation_enabled?: boolean` Query param: Flag whether schema is enabled for validation. ### Returns - `OldPublicSchema` - `created_at: string` - `kind: "openapi_v3"` Kind of schema - `"openapi_v3"` - `name: string` Name of the schema - `schema_id: string` UUID. - `source?: string` Source of the schema - `validation_enabled?: boolean` Flag whether schema is enabled for validation. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const oldPublicSchema of client.apiGateway.userSchemas.list({ zone_id: '023e105f4ecef8ad9ca31a8372d0c353', })) { console.log(oldPublicSchema.schema_id); } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": [ { "created_at": "2014-01-01T05:20:00.12345Z", "kind": "openapi_v3", "name": "petstore schema", "schema_id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "source": "", "validation_enabled": true } ], "success": true, "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ``` ## Retrieve information about a specific schema on a zone `client.apiGateway.userSchemas.get(stringschemaId, UserSchemaGetParamsparams, RequestOptionsoptions?): OldPublicSchema` **get** `/zones/{zone_id}/api_gateway/user_schemas/{schema_id}` Gets detailed information about a specific uploaded OpenAPI schema, including its contents and validation configuration. ### Parameters - `schemaId: string` - `params: UserSchemaGetParams` - `zone_id: string` Path param: Identifier. - `omit_source?: boolean` Query param: Omit the source-files of schemas and only retrieve their meta-data. ### Returns - `OldPublicSchema` - `created_at: string` - `kind: "openapi_v3"` Kind of schema - `"openapi_v3"` - `name: string` Name of the schema - `schema_id: string` UUID. - `source?: string` Source of the schema - `validation_enabled?: boolean` Flag whether schema is enabled for validation. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const oldPublicSchema = await client.apiGateway.userSchemas.get( 'f174e90a-fafe-4643-bbbc-4a0ed4fc8415', { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' }, ); console.log(oldPublicSchema.schema_id); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "created_at": "2014-01-01T05:20:00.12345Z", "kind": "openapi_v3", "name": "petstore schema", "schema_id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "source": "", "validation_enabled": true }, "success": true } ``` ## Upload a schema to a zone `client.apiGateway.userSchemas.create(UserSchemaCreateParamsparams, RequestOptionsoptions?): UserSchemaCreateResponse` **post** `/zones/{zone_id}/api_gateway/user_schemas` Upload a schema to a zone ### Parameters - `params: UserSchemaCreateParams` - `zone_id: string` Path param: Identifier. - `file: Uploadable` Body param: Schema file bytes - `kind: "openapi_v3"` Body param: Kind of schema - `"openapi_v3"` - `name?: string` Body param: Name of the schema - `validation_enabled?: "true" | "false"` Body param: Flag whether schema is enabled for validation. - `"true"` - `"false"` ### Returns - `UserSchemaCreateResponse` - `schema: OldPublicSchema` - `created_at: string` - `kind: "openapi_v3"` Kind of schema - `"openapi_v3"` - `name: string` Name of the schema - `schema_id: string` UUID. - `source?: string` Source of the schema - `validation_enabled?: boolean` Flag whether schema is enabled for validation. - `upload_details?: UploadDetails` - `warnings?: Array` Diagnostic warning events that occurred during processing. These events are non-critical errors found within the schema. - `code: number` Code that identifies the event that occurred. - `locations?: Array` JSONPath location(s) in the schema where these events were encountered. See for JSONPath specification. - `message?: string` Diagnostic message that describes the event. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const userSchema = await client.apiGateway.userSchemas.create({ zone_id: '023e105f4ecef8ad9ca31a8372d0c353', file: fs.createReadStream('path/to/file'), kind: 'openapi_v3', }); console.log(userSchema.schema); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "schema": { "created_at": "2014-01-01T05:20:00.12345Z", "kind": "openapi_v3", "name": "petstore schema", "schema_id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "source": "", "validation_enabled": true }, "upload_details": { "warnings": [ { "code": 28, "locations": [ ".paths[\"/user/{username}\"].put" ], "message": "unsupported media type: application/octet-stream" } ] } }, "success": true } ``` ## Enable validation for a schema `client.apiGateway.userSchemas.edit(stringschemaId, UserSchemaEditParamsparams, RequestOptionsoptions?): OldPublicSchema` **patch** `/zones/{zone_id}/api_gateway/user_schemas/{schema_id}` Activates schema validation for an uploaded OpenAPI schema. Requests to matching endpoints will be validated against the schema definitions. ### Parameters - `schemaId: string` - `params: UserSchemaEditParams` - `zone_id: string` Path param: Identifier. - `validation_enabled?: true` Body param: Flag whether schema is enabled for validation. - `true` ### Returns - `OldPublicSchema` - `created_at: string` - `kind: "openapi_v3"` Kind of schema - `"openapi_v3"` - `name: string` Name of the schema - `schema_id: string` UUID. - `source?: string` Source of the schema - `validation_enabled?: boolean` Flag whether schema is enabled for validation. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const oldPublicSchema = await client.apiGateway.userSchemas.edit( 'f174e90a-fafe-4643-bbbc-4a0ed4fc8415', { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' }, ); console.log(oldPublicSchema.schema_id); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "created_at": "2014-01-01T05:20:00.12345Z", "kind": "openapi_v3", "name": "petstore schema", "schema_id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "source": "", "validation_enabled": true }, "success": true } ``` ## Delete a schema `client.apiGateway.userSchemas.delete(stringschemaId, UserSchemaDeleteParamsparams, RequestOptionsoptions?): UserSchemaDeleteResponse` **delete** `/zones/{zone_id}/api_gateway/user_schemas/{schema_id}` Permanently removes an uploaded OpenAPI schema from API Shield schema validation. Operations using this schema will lose their validation rules. ### Parameters - `schemaId: string` - `params: UserSchemaDeleteParams` - `zone_id: string` Identifier. ### Returns - `UserSchemaDeleteResponse` - `errors: Message` - `code: number` - `message: string` - `documentation_url?: string` - `source?: Source` - `pointer?: string` - `messages: Message` - `success: true` Whether the API call was successful. - `true` ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const userSchema = await client.apiGateway.userSchemas.delete( 'f174e90a-fafe-4643-bbbc-4a0ed4fc8415', { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' }, ); console.log(userSchema.errors); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "success": true } ``` ## Domain Types ### Message - `Message = Array` - `code: number` - `message: string` - `documentation_url?: string` - `source?: Source` - `pointer?: string` ### Old Public Schema - `OldPublicSchema` - `created_at: string` - `kind: "openapi_v3"` Kind of schema - `"openapi_v3"` - `name: string` Name of the schema - `schema_id: string` UUID. - `source?: string` Source of the schema - `validation_enabled?: boolean` Flag whether schema is enabled for validation. ### User Schema Create Response - `UserSchemaCreateResponse` - `schema: OldPublicSchema` - `created_at: string` - `kind: "openapi_v3"` Kind of schema - `"openapi_v3"` - `name: string` Name of the schema - `schema_id: string` UUID. - `source?: string` Source of the schema - `validation_enabled?: boolean` Flag whether schema is enabled for validation. - `upload_details?: UploadDetails` - `warnings?: Array` Diagnostic warning events that occurred during processing. These events are non-critical errors found within the schema. - `code: number` Code that identifies the event that occurred. - `locations?: Array` JSONPath location(s) in the schema where these events were encountered. See for JSONPath specification. - `message?: string` Diagnostic message that describes the event. ### User Schema Delete Response - `UserSchemaDeleteResponse` - `errors: Message` - `code: number` - `message: string` - `documentation_url?: string` - `source?: Source` - `pointer?: string` - `messages: Message` - `success: true` Whether the API call was successful. - `true` # Operations ## Retrieve all operations from a schema. `client.apiGateway.userSchemas.operations.list(stringschemaId, OperationListParamsparams, RequestOptionsoptions?): V4PagePaginationArray` **get** `/zones/{zone_id}/api_gateway/user_schemas/{schema_id}/operations` Retrieves all operations from the schema. Operations that already exist in API Shield Endpoint Management will be returned as full operations. ### Parameters - `schemaId: string` - `params: OperationListParams` - `zone_id: string` Path param: Identifier. - `endpoint?: string` Query param: Filter results to only include endpoints containing this pattern. - `feature?: Array<"thresholds" | "parameter_schemas" | "schema_info">` Query param: Add feature(s) to the results. The feature name that is given here corresponds to the resulting feature object. Have a look at the top-level object description for more details on the specific meaning. - `"thresholds"` - `"parameter_schemas"` - `"schema_info"` - `host?: Array` Query param: Filter results to only include the specified hosts. - `method?: Array` Query param: Filter results to only include the specified HTTP methods. - `operation_status?: "new" | "existing"` Query param: Filter results by whether operations exist in API Shield Endpoint Management or not. `new` will just return operations from the schema that do not exist in API Shield Endpoint Management. `existing` will just return operations from the schema that already exist in API Shield Endpoint Management. - `"new"` - `"existing"` - `page?: number` Query param: Page number of paginated results. - `per_page?: number` Query param: Maximum number of results per page. ### Returns - `OperationListResponse = APIShieldOperation | APIShieldBasicOperation` - `APIShieldOperation` - `endpoint: string` The endpoint which can contain path parameter templates in curly braces, each will be replaced from left to right with {varN}, starting with {var1}, during insertion. This will further be Cloudflare-normalized upon insertion. See: https://developers.cloudflare.com/rules/normalization/how-it-works/. - `host: string` RFC3986-compliant host. - `last_updated: string` - `method: "GET" | "POST" | "HEAD" | 6 more` The HTTP method used to access the endpoint. - `"GET"` - `"POST"` - `"HEAD"` - `"OPTIONS"` - `"PUT"` - `"DELETE"` - `"CONNECT"` - `"PATCH"` - `"TRACE"` - `operation_id: string` UUID. - `features?: APIShieldOperationFeatureThresholds | APIShieldOperationFeatureParameterSchemas | APIShieldOperationFeatureAPIRouting | 2 more` - `APIShieldOperationFeatureThresholds` - `thresholds?: Thresholds` - `auth_id_tokens?: number` The total number of auth-ids seen across this calculation. - `data_points?: number` The number of data points used for the threshold suggestion calculation. - `last_updated?: string` - `p50?: number` The p50 quantile of requests (in period_seconds). - `p90?: number` The p90 quantile of requests (in period_seconds). - `p99?: number` The p99 quantile of requests (in period_seconds). - `period_seconds?: number` The period over which this threshold is suggested. - `requests?: number` The estimated number of requests covered by these calculations. - `suggested_threshold?: number` The suggested threshold in requests done by the same auth_id or period_seconds. - `APIShieldOperationFeatureParameterSchemas` - `parameter_schemas: ParameterSchemas` - `last_updated?: string` - `parameter_schemas?: ParameterSchemas` An operation schema object containing a response. - `parameters?: Array` An array containing the learned parameter schemas. - `responses?: unknown` An empty response object. This field is required to yield a valid operation schema. - `APIShieldOperationFeatureAPIRouting` - `api_routing?: APIRouting` API Routing settings on endpoint. - `last_updated?: string` - `route?: string` Target route. - `APIShieldOperationFeatureConfidenceIntervals` - `confidence_intervals?: ConfidenceIntervals` - `last_updated?: string` - `suggested_threshold?: SuggestedThreshold` - `confidence_intervals?: ConfidenceIntervals` - `p90?: P90` Upper and lower bound for percentile estimate - `lower?: number` Lower bound for percentile estimate - `upper?: number` Upper bound for percentile estimate - `p95?: P95` Upper and lower bound for percentile estimate - `lower?: number` Lower bound for percentile estimate - `upper?: number` Upper bound for percentile estimate - `p99?: P99` Upper and lower bound for percentile estimate - `lower?: number` Lower bound for percentile estimate - `upper?: number` Upper bound for percentile estimate - `mean?: number` Suggested threshold. - `APIShieldOperationFeatureSchemaInfo` - `schema_info?: SchemaInfo` - `active_schema?: ActiveSchema` Schema active on endpoint. - `id?: string` UUID. - `created_at?: string` - `is_learned?: boolean` True if schema is Cloudflare-provided. - `name?: string` Schema file name. - `learned_available?: boolean` True if a Cloudflare-provided learned schema is available for this endpoint. - `mitigation_action?: "none" | "log" | "block" | null` Action taken on requests failing validation. - `"none"` - `"log"` - `"block"` - `APIShieldBasicOperation` - `endpoint: string` The endpoint which can contain path parameter templates in curly braces, each will be replaced from left to right with {varN}, starting with {var1}, during insertion. This will further be Cloudflare-normalized upon insertion. See: https://developers.cloudflare.com/rules/normalization/how-it-works/. - `host: string` RFC3986-compliant host. - `method: "GET" | "POST" | "HEAD" | 6 more` The HTTP method used to access the endpoint. - `"GET"` - `"POST"` - `"HEAD"` - `"OPTIONS"` - `"PUT"` - `"DELETE"` - `"CONNECT"` - `"PATCH"` - `"TRACE"` ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const operationListResponse of client.apiGateway.userSchemas.operations.list( 'f174e90a-fafe-4643-bbbc-4a0ed4fc8415', { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' }, )) { console.log(operationListResponse); } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": [ { "endpoint": "/api/v1/users/{var1}", "host": "www.example.com", "last_updated": "2014-01-01T05:20:00.12345Z", "method": "GET", "operation_id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "features": { "thresholds": { "auth_id_tokens": 0, "data_points": 0, "last_updated": "2014-01-01T05:20:00.12345Z", "p50": 0, "p90": 0, "p99": 0, "period_seconds": 0, "requests": 0, "suggested_threshold": 0 } } } ], "success": true, "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ``` ## Domain Types ### Operation List Response - `OperationListResponse = APIShieldOperation | APIShieldBasicOperation` - `APIShieldOperation` - `endpoint: string` The endpoint which can contain path parameter templates in curly braces, each will be replaced from left to right with {varN}, starting with {var1}, during insertion. This will further be Cloudflare-normalized upon insertion. See: https://developers.cloudflare.com/rules/normalization/how-it-works/. - `host: string` RFC3986-compliant host. - `last_updated: string` - `method: "GET" | "POST" | "HEAD" | 6 more` The HTTP method used to access the endpoint. - `"GET"` - `"POST"` - `"HEAD"` - `"OPTIONS"` - `"PUT"` - `"DELETE"` - `"CONNECT"` - `"PATCH"` - `"TRACE"` - `operation_id: string` UUID. - `features?: APIShieldOperationFeatureThresholds | APIShieldOperationFeatureParameterSchemas | APIShieldOperationFeatureAPIRouting | 2 more` - `APIShieldOperationFeatureThresholds` - `thresholds?: Thresholds` - `auth_id_tokens?: number` The total number of auth-ids seen across this calculation. - `data_points?: number` The number of data points used for the threshold suggestion calculation. - `last_updated?: string` - `p50?: number` The p50 quantile of requests (in period_seconds). - `p90?: number` The p90 quantile of requests (in period_seconds). - `p99?: number` The p99 quantile of requests (in period_seconds). - `period_seconds?: number` The period over which this threshold is suggested. - `requests?: number` The estimated number of requests covered by these calculations. - `suggested_threshold?: number` The suggested threshold in requests done by the same auth_id or period_seconds. - `APIShieldOperationFeatureParameterSchemas` - `parameter_schemas: ParameterSchemas` - `last_updated?: string` - `parameter_schemas?: ParameterSchemas` An operation schema object containing a response. - `parameters?: Array` An array containing the learned parameter schemas. - `responses?: unknown` An empty response object. This field is required to yield a valid operation schema. - `APIShieldOperationFeatureAPIRouting` - `api_routing?: APIRouting` API Routing settings on endpoint. - `last_updated?: string` - `route?: string` Target route. - `APIShieldOperationFeatureConfidenceIntervals` - `confidence_intervals?: ConfidenceIntervals` - `last_updated?: string` - `suggested_threshold?: SuggestedThreshold` - `confidence_intervals?: ConfidenceIntervals` - `p90?: P90` Upper and lower bound for percentile estimate - `lower?: number` Lower bound for percentile estimate - `upper?: number` Upper bound for percentile estimate - `p95?: P95` Upper and lower bound for percentile estimate - `lower?: number` Lower bound for percentile estimate - `upper?: number` Upper bound for percentile estimate - `p99?: P99` Upper and lower bound for percentile estimate - `lower?: number` Lower bound for percentile estimate - `upper?: number` Upper bound for percentile estimate - `mean?: number` Suggested threshold. - `APIShieldOperationFeatureSchemaInfo` - `schema_info?: SchemaInfo` - `active_schema?: ActiveSchema` Schema active on endpoint. - `id?: string` UUID. - `created_at?: string` - `is_learned?: boolean` True if schema is Cloudflare-provided. - `name?: string` Schema file name. - `learned_available?: boolean` True if a Cloudflare-provided learned schema is available for this endpoint. - `mitigation_action?: "none" | "log" | "block" | null` Action taken on requests failing validation. - `"none"` - `"log"` - `"block"` - `APIShieldBasicOperation` - `endpoint: string` The endpoint which can contain path parameter templates in curly braces, each will be replaced from left to right with {varN}, starting with {var1}, during insertion. This will further be Cloudflare-normalized upon insertion. See: https://developers.cloudflare.com/rules/normalization/how-it-works/. - `host: string` RFC3986-compliant host. - `method: "GET" | "POST" | "HEAD" | 6 more` The HTTP method used to access the endpoint. - `"GET"` - `"POST"` - `"HEAD"` - `"OPTIONS"` - `"PUT"` - `"DELETE"` - `"CONNECT"` - `"PATCH"` - `"TRACE"` # Hosts ## Retrieve schema hosts in a zone `client.apiGateway.userSchemas.hosts.list(HostListParamsparams, RequestOptionsoptions?): V4PagePaginationArray` **get** `/zones/{zone_id}/api_gateway/user_schemas/hosts` Lists all unique hosts found in uploaded OpenAPI schemas for the zone. Useful for understanding which domains have schema coverage. ### Parameters - `params: HostListParams` - `zone_id: string` Path param: Identifier. - `page?: number` Query param: Page number of paginated results. - `per_page?: number` Query param: Maximum number of results per page. ### Returns - `HostListResponse` - `created_at: string` - `hosts: Array` Hosts serving the schema, e.g zone.host.com - `name: string` Name of the schema - `schema_id: string` UUID. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const hostListResponse of client.apiGateway.userSchemas.hosts.list({ zone_id: '023e105f4ecef8ad9ca31a8372d0c353', })) { console.log(hostListResponse.schema_id); } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "success": true, "result": [ { "created_at": "2014-01-01T05:20:00.12345Z", "hosts": [ "string" ], "name": "petstore schema", "schema_id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415" } ], "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ``` ## Domain Types ### Host List Response - `HostListResponse` - `created_at: string` - `hosts: Array` Hosts serving the schema, e.g zone.host.com - `name: string` Name of the schema - `schema_id: string` UUID.